| Package | gulp-swagger |
| Description | 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. |
| Node Version | >= 0.8 |
npm install gulp-swaggerOutput fully parsed schema:
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:
var gulp = require('gulp');
var swagger = require('gulp-swagger');
gulp.task('api', function() {
gulp.src('./src/api/index.yaml')
.pipe(swagger({
filename: 'api.js',
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:
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, 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. Gulp-Swagger also passes the swagger schema as well as a compilation of all JSON-schemas to mustache options. This is useful if you want to carry schema validation validation on the client-side:
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: {
// Silly E.g. Pasing variables to mustache to envify the templates...
process: { env: { 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']);
});So inside your mustache template, you can:
var swagger = {{&swagger}};
var schemas = {{&JSONSchemas}};
The JSONSchemas mustache variable will render as somehing like:
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"
}
}
}
}
}
}
};
The provided example implements client-side JSON schema validation using 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.
- Test coverage
- Built-in schema validation
I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.
Gulp-Swagger is 100% free and open-source, under the MIT license. Use it however you want.