Gulp plugin that parses Swagger specs in JSON or YAML format, validates against the official Swagger 2.0 schema, dereferences all $ref pointers, including pointers to external files and generates client-side API code.
npm install gulp-swagger| | |
| ----------- | ------------ |
| Package | gulp-swagger |
| Description | [Gulp][gulp] plugin that parses [Swagger][swagger] specs in JSON or YAML format, validates against the official [Swagger 2.0 schema][swagger2spec], dereferences all $ref pointers, including pointers to external files and generates client-side API code. |
| Node Version | >= 0.8 |
Install
--------------------------
``js`
npm install gulp-swagger
Usage
--------------------------
Output fully parsed schema:
`js
var gulp = require('gulp');
var swagger = require('gulp-swagger');
gulp.task('schema', function() {
gulp.src('./src/api/index.yaml')
.pipe(swagger('schema.json'))
.pipe(gulp.dest('./build'));
});
gulp.task('default', ['schema']);
`
Generate client-side API based on schema for AngularJS:
`js
var gulp = require('gulp');
var swagger = require('gulp-swagger');
gulp.task('api', function() {
gulp.src('./src/api/index.yaml')
.pipe(swagger({
filename: 'api.js',
codegen: {
type: 'angular' // type can be 'angular', 'node' or 'custom' (default).
}
}))
.pipe(gulp.dest('./api'));
});
gulp.task('default', ['api']);
// Rerun the task when a file changes
gulp.task('watch', function () {
gulp.watch('./src/api/*.yaml', ['api']);
});
`
Generate client-side API based on schema using custom templates:
`js
var gulp = require('gulp');
var swagger = require('gulp-swagger');
gulp.task('api', function() {
gulp.src('./src/api/index.yaml')
.pipe(swagger({
filename: 'api.js',
codegen: {
template: {
class: './src/templates/api-class.mustache',
method: './src/templates/api-method.mustache',
request: './src/templates/api-request.mustache'
}
}
}))
.pipe(gulp.dest('./api'));
});
gulp.task('default', ['api']);
// Rerun the task when a file changes
gulp.task('watch', function () {
gulp.watch('./src/api/*.yaml', ['api']);
});
`
Differently from [Swagger to JS Codegen][swagger-js-codegen], Gulp-Swagger does not require the template field to be on the format template: { class: "...", method: "...", request: "..." }. You can pass either of them as you want. Eg. say that your custom method and request are super simple and you only really need one class template, you could only pass template: { class: "..." }. For this reason, as a shortcut, template can also be a string: template: "...". Gulp-Swagger allows to you pass mustache options along to Codegen.
`js
var gulp = require('gulp');
var swagger = require('gulp-swagger');
gulp.task('api', function() {
gulp.src('./src/api/index.yaml')
.pipe(swagger({
filename: 'api.js',
codegen: {
template: './src/templates/api.mustache',
mustache: {
// E.g. Passing variables to mustache to envify the templates...
NODE_ENV: process.env.NODE_ENV
}
}
}))
.pipe(gulp.dest('./api'));
});
gulp.task('default', ['api']);
// Rerun the task when a file changes
gulp.task('watch', function () {
gulp.watch('./src/api/*.yaml', ['api']);
});
`
Hadling Circular reference object :
While parsing the JSON back from the string use "circular-json" to parse the string to JSON by filling all the circular reference.
`js
var CircularJSON = require('circular-json');
CircularJSON.parse(jsonString);
`
Gulp-Swagger also passes the swagger schema to mustache options, both as an object (swaggerObject) and as a stringified JSON (swaggerJSON). Better even, there's also a compilation of all JSON-schemas passed to mustache options, handy if you want to carry on schema validation on the client-side. So inside your mustache template, you can do things like:
`
var basePath = '{{&swaggerObject.basePath}}'; // swagger js object you can traverse
var swagger = {{&swaggerJSON}}; // swagger schema, JSON-stringified
var schemas = {{&JSONSchemas}}; // compilation of all request/response body JSON schemas, JSON-stringified
The JSONSchemas mustache variable will render as:
`
var schemas = {
"/pets": {
"get": {
"responses": {
"200": {
"type": "array",
"items": {
"required": ["id", "name"],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
}
},
"default": {
"required": ["code", "message"],
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
},
"post": {
"responses": {
"200": {
"required": ["id", "name"],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
},
"default": {
"required": ["code", "message"],
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
}
},
"/pets/{id}": {
"get": {
"responses": {
"200": {
"required": ["id", "name"],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
},
"default": {
"required": ["code", "message"],
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
},
"delete": {
"responses": {
"204": {},
"default": {
"required": ["code", "message"],
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
}
}
};
Note: By default, the parser will dereference all internal $refs, which could result in a bloated json when many paths share the same schema/parameters/responses, etc. You can have fine grained control over the parser by using the parser option which you can use to customize how the API is parsed, resolved, dereferenced, etc. For usage, please refer to the SwaggerParser Options Documentation.
`
.pipe(swagger({
filename: 'api.js',
parser: {/ swagger-parser options /}
})
Example Implementation
--------------------------
The provided example implements client-side JSON schema validation using [tv4][tv4] of both Ajax requests and responses.
To play with the example, download this repo. Point your terminal to the example folder and run: $ npm run setup. Then open http://localhost:8888 in your browser, open the dev tools console and play around with the API` global object.
Roadmap
--------------------------
- [ ] Test coverage
- [ ] Built-in schema validation
See Also
--------------------------
- [Gulp][gulp]
- [Swagger][swagger]
- [Swagger-Parser][swagger-parser]
- [Swagger to JS Codegen][swagger-js-codegen]
Contributing
--------------------------
I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.
License
--------------------------
Gulp-Swagger is 100% free and open-source, under the MIT license. Use it however you want.
[gulp]: http://github.com/gulpjs/gulp
[swagger]: http://swagger.io
[swagger2spec]: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md
[swagger-parser]: https://github.com/BigstickCarpet/swagger-parser
[swagger-tools]: https://github.com/apigee-127/swagger-tools
[swagger-js-codegen]: https://github.com/wcandillon/swagger-js-codegen
[tv4]: https://github.com/geraintluff/tv4