0
# Validation and Conversion
1
2
Swagger document validation and format conversion utilities for ensuring specification compliance and migrating between Swagger versions.
3
4
## Capabilities
5
6
### Document Validation
7
8
Validates Swagger documents against the Swagger 2.0 specification with detailed error and warning reporting.
9
10
```bash { .api }
11
swagger validate [swaggerFile] [options]
12
13
# Options:
14
# -j, --json Output validation results as JSON
15
```
16
17
**Usage Examples:**
18
19
```bash
20
# Validate specific file
21
swagger validate api/swagger/swagger.yaml
22
23
# Validate with JSON output
24
swagger validate api/swagger/swagger.yaml --json
25
26
# Validate from stdin (pipe support)
27
cat swagger.yaml | swagger validate
28
29
# Validate JSON format
30
swagger validate api-spec.json
31
```
32
33
**Programmatic Usage:**
34
35
```javascript { .api }
36
/**
37
* Validate Swagger document
38
* @param {string} file - Path to Swagger file (null for stdin)
39
* @param {Object} options - Validation options
40
* @param {boolean} options.json - Output as JSON
41
* @param {Function} cb - Callback function
42
*/
43
function validate(file, options, cb);
44
```
45
46
**Validation with Spec Utility:**
47
48
```javascript { .api }
49
/**
50
* Validate Swagger specification object
51
* @param {Object} swagger - Swagger specification object
52
* @param {Object} options - Validation options
53
* @param {boolean} options.json - Output results as JSON
54
* @param {Function} cb - Callback function (err, results)
55
*/
56
function validateSwagger(swagger, options, cb);
57
```
58
59
**Usage Examples:**
60
61
```javascript
62
const { validate } = require('swagger/lib/commands/commands');
63
const spec = require('swagger/lib/util/spec');
64
65
// Validate file
66
validate('api/swagger/swagger.yaml', { json: false }, function(err, result) {
67
if (err) {
68
console.error('Validation failed:', err);
69
} else {
70
console.log('Validation result:', result);
71
}
72
});
73
74
// Validate specification object
75
const swaggerSpec = {
76
swagger: '2.0',
77
info: { title: 'My API', version: '1.0.0' },
78
paths: {}
79
};
80
81
spec.validateSwagger(swaggerSpec, { json: false }, function(err, result) {
82
if (err) {
83
console.error('Validation error:', err);
84
} else {
85
console.log(result); // "Results: 0 errors, 0 warnings"
86
}
87
});
88
```
89
90
### Format Conversion
91
92
Converts Swagger 1.2 documents to Swagger 2.0 format with support for multiple API declaration files.
93
94
```bash { .api }
95
swagger convert <swaggerFile> [apiDeclarations...] [options]
96
97
# Options:
98
# -o, --output-file <fileName> Write output to specified file
99
```
100
101
**Usage Examples:**
102
103
```bash
104
# Convert single file to stdout
105
swagger convert resource-list.json
106
107
# Convert with API declarations
108
swagger convert resource-list.json pet-api.json store-api.json
109
110
# Convert and save to file
111
swagger convert resource-list.json --output-file swagger-2.0.yaml
112
113
# Convert multiple declarations to file
114
swagger convert resource-list.json pet.json store.json user.json --output-file api-v2.yaml
115
```
116
117
**Programmatic Usage:**
118
119
```javascript { .api }
120
/**
121
* Convert Swagger 1.2 to Swagger 2.0
122
* @param {string} filePath - Path to main Swagger 1.2 resource listing
123
* @param {string[]} apiDeclarations - Array of API declaration file paths
124
* @param {Object} options - Conversion options
125
* @param {string} options.outputFile - Output file path
126
* @param {Function} cb - Callback function
127
*/
128
function convert(filePath, apiDeclarations, options, cb);
129
```
130
131
**Usage Examples:**
132
133
```javascript
134
const { convert } = require('swagger/lib/commands/commands');
135
136
// Convert to callback
137
convert(
138
'resource-list.json',
139
['pet-api.json', 'store-api.json'],
140
{},
141
function(err, result) {
142
if (err) {
143
console.error('Conversion failed:', err);
144
} else {
145
console.log('Converted YAML:', result);
146
}
147
}
148
);
149
150
// Convert and save to file
151
convert(
152
'resource-list.json',
153
['pet-api.json'],
154
{ outputFile: 'swagger-v2.yaml' },
155
function(err) {
156
if (err) {
157
console.error('Conversion failed:', err);
158
} else {
159
console.log('Conversion saved to swagger-v2.yaml');
160
}
161
}
162
);
163
```
164
165
### Documentation Access
166
167
Opens Swagger specification documentation in the system browser.
168
169
```bash { .api }
170
swagger docs
171
```
172
173
This command opens the official Swagger 2.0 specification documentation at:
174
`https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md`
175
176
## Input Format Support
177
178
### File Format Detection
179
180
The validation and conversion utilities automatically detect and parse multiple input formats:
181
182
```javascript { .api }
183
/**
184
* Parse input data as JSON or YAML
185
* @param {string} data - Input data string
186
* @returns {Object} Parsed object
187
*/
188
function parse(data);
189
190
/**
191
* Check if data is JSON format
192
* @param {string} data - Input data string
193
* @returns {boolean} True if JSON format
194
*/
195
function isJSON(data);
196
```
197
198
**Supported Formats:**
199
- **JSON**: Standard JSON format with `.json` extension
200
- **YAML**: YAML format with `.yaml` or `.yml` extension
201
- **Stdin**: Pipe input from other commands
202
203
### Error Handling
204
205
Both validation and conversion provide detailed error reporting:
206
207
**Validation Errors:**
208
- Specification compliance errors
209
- Schema validation failures
210
- Path and operation validation issues
211
- Parameter and response validation problems
212
213
**Conversion Errors:**
214
- File not found errors
215
- Invalid Swagger 1.2 format
216
- Missing API declaration files
217
- Parsing errors for malformed JSON/YAML
218
219
**Error Output Format:**
220
221
```
222
Project Errors
223
--------------
224
#/paths/users/get: Missing required property 'responses'
225
#/definitions/User/properties/id: Invalid type 'integer', expected 'number'
226
227
Project Warnings
228
----------------
229
#/paths/users/get: Unused parameter 'filter'
230
#/definitions/User: Definition is not referenced by any operation
231
232
Results: 2 errors, 1 warnings
233
```
234
235
## Integration with Project Workflow
236
237
### Automatic Validation
238
239
Validation is automatically performed during:
240
- Project verification (`swagger project verify`)
241
- Editor operations (real-time validation)
242
- Test generation (specification validation before test creation)
243
244
### Conversion Workflow
245
246
Typical conversion workflow for migrating from Swagger 1.2:
247
248
1. **Prepare Files**: Gather resource listing and API declaration files
249
2. **Convert**: Use `swagger convert` to generate Swagger 2.0 specification
250
3. **Validate**: Run `swagger validate` on converted specification
251
4. **Import**: Use converted specification in new Swagger project
252
5. **Refine**: Edit using `swagger project edit` for final adjustments