0
# Editor Integration
1
2
Browser-based Swagger editor integration with real-time validation, file synchronization, and built-in development tools for API specification editing.
3
4
## Capabilities
5
6
### Swagger Editor
7
8
Launches an integrated browser-based Swagger editor with real-time validation and automatic file synchronization.
9
10
```bash { .api }
11
swagger project edit [directory] [options]
12
13
# Options:
14
# -s, --silent Do not open browser automatically
15
# --host <host> Hostname for editor server (default: 127.0.0.1)
16
# -p, --port <port> Port for editor server (default: auto-assigned)
17
```
18
19
**Usage Examples:**
20
21
```bash
22
# Open editor for current project
23
swagger project edit
24
25
# Open editor on specific host and port
26
swagger project edit --host 0.0.0.0 --port 8080
27
28
# Start editor server without opening browser
29
swagger project edit --silent
30
```
31
32
**Programmatic Usage:**
33
34
```javascript { .api }
35
/**
36
* Launch Swagger editor for project
37
* @param {string} directory - Project directory
38
* @param {Object} options - Editor options
39
* @param {boolean} options.silent - Don't open browser
40
* @param {string} options.host - Server hostname
41
* @param {number} options.port - Server port
42
* @param {Function} cb - Callback function
43
*/
44
function edit(directory, options, cb);
45
```
46
47
The editor provides:
48
- Real-time Swagger 2.0 validation
49
- Syntax highlighting for YAML/JSON
50
- Interactive API documentation
51
- Try-it functionality for testing endpoints
52
- Automatic file synchronization with local project
53
54
### Project Browser Client
55
56
Opens the running project in a browser for testing and interaction with the live API.
57
58
```bash { .api }
59
swagger project open [directory]
60
```
61
62
**Usage Examples:**
63
64
```bash
65
# Open current project in browser
66
swagger project open
67
68
# Open specific project
69
swagger project open ./my-api
70
```
71
72
**Programmatic Usage:**
73
74
```javascript { .api }
75
/**
76
* Open project in browser
77
* @param {string} directory - Project directory
78
* @param {Object} options - Browser options
79
* @param {Function} cb - Callback function
80
*/
81
function open(directory, options, cb);
82
```
83
84
## Editor Configuration
85
86
### Default Configuration
87
88
The Swagger editor is configured with the following default settings:
89
90
```javascript { .api }
91
const editorConfig = {
92
analytics: { google: { id: null } },
93
disableCodeGen: true,
94
disableNewUserIntro: true,
95
examplesFolder: '/spec-files/',
96
exampleFiles: [],
97
autocompleteExtension: {},
98
useBackendForStorage: true,
99
backendEndpoint: '/editor/spec',
100
backendHealthCheckTimeout: 5000,
101
useYamlBackend: true,
102
disableFileMenu: true,
103
enableTryIt: true,
104
headerBranding: false,
105
brandingCssClass: null,
106
schemaUrl: '/schema/swagger.json',
107
importProxyUrl: 'https://cors-it.herokuapp.com/?url='
108
};
109
```
110
111
### File Synchronization
112
113
The editor automatically synchronizes changes with the local Swagger specification file:
114
115
- **Load Path**: `/editor/spec` - Editor fetches current specification
116
- **Save Path**: `/editor/spec` - Editor saves changes via PUT requests
117
- **Config Path**: `/config/defaults.json` - Editor configuration endpoint
118
- **Default File**: `api/swagger/swagger.yaml` - Local specification file
119
120
### Server Integration
121
122
The editor runs as a Connect middleware server with the following endpoints:
123
124
```javascript { .api }
125
// Server paths
126
const SWAGGER_EDITOR_SERVE_PATH = '/'; // Editor static files
127
const SWAGGER_EDITOR_LOAD_PATH = '/editor/spec'; // Specification loading
128
const SWAGGER_EDITOR_SAVE_PATH = '/editor/spec'; // Specification saving
129
const SWAGGER_EDITOR_CONFIG_PATH = '/config/defaults.json'; // Configuration
130
```
131
132
## Browser Utilities
133
134
### Cross-Platform Browser Support
135
136
```javascript { .api }
137
/**
138
* Open URL in system browser
139
* @param {string} url - URL to open
140
* @param {Function} cb - Callback function
141
* @param {string} platform - Platform override for testing
142
*/
143
function open(url, cb, platform);
144
```
145
146
**Platform Support:**
147
148
```javascript { .api }
149
const platformOpeners = {
150
darwin: function(url, cb), // macOS
151
win32: function(url, cb), // Windows
152
linux: function(url, cb), // Linux
153
other: function(url, cb) // Other platforms
154
};
155
```
156
157
**Usage Examples:**
158
159
```javascript
160
const browser = require('swagger/lib/util/browser');
161
162
// Open Swagger documentation
163
browser.open('https://swagger.io/docs/', function(err) {
164
if (err) console.error('Failed to open browser:', err);
165
});
166
167
// Open local development server
168
browser.open('http://localhost:10010', function(err) {
169
if (err) console.error('Failed to open browser:', err);
170
});
171
```
172
173
## Network Utilities
174
175
### Port Availability Checking
176
177
```javascript { .api }
178
/**
179
* Check if a network port is open/available
180
* @param {number} port - Port number to check
181
* @param {number} timeout - Timeout in milliseconds (default: 100)
182
* @param {Function} cb - Callback function (err, isOpen)
183
*/
184
function isPortOpen(port, timeout, cb);
185
```
186
187
**Usage Examples:**
188
189
```javascript
190
const netutil = require('swagger/lib/util/net');
191
192
// Check if project server is running
193
netutil.isPortOpen(10010, function(err, isOpen) {
194
if (err) {
195
console.error('Error checking port:', err);
196
} else if (isOpen) {
197
console.log('Server is running on port 10010');
198
} else {
199
console.log('Port 10010 is not in use');
200
}
201
});
202
203
// Check with custom timeout
204
netutil.isPortOpen(8080, 500, function(err, isOpen) {
205
console.log('Port 8080 is', isOpen ? 'open' : 'closed');
206
});
207
```
208
209
This utility is used internally to verify that the development server is running before attempting to open the project in a browser.