Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kant2002/gulp-ts-swagger
Swagger generator for TypeScript
https://github.com/kant2002/gulp-ts-swagger
Last synced: 18 days ago
JSON representation
Swagger generator for TypeScript
- Host: GitHub
- URL: https://github.com/kant2002/gulp-ts-swagger
- Owner: kant2002
- License: mit
- Created: 2016-06-19T12:35:30.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2016-06-25T10:49:12.000Z (over 8 years ago)
- Last Synced: 2024-10-11T20:49:31.736Z (about 1 month ago)
- Language: TypeScript
- Size: 9.77 KB
- Stars: 1
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gulp-ts-swagger v1.0.0
--------------------------
| | |
| ----------- | ------------ |
| Package | gulp-ts-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-ts-swagger
```
Usage
--------------------------
Output fully parsed schema:
```js
var gulp = require('gulp');
var swagger = require('gulp-ts-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-ts-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:
```js
var gulp = require('gulp');
var swagger = require('gulp-ts-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-TS-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-ts-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']);
});
```
Gulp-TS-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"
}
}
}
}
}
}
};
```
Example
--------------------------
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](https://github.com/kant2002/gulp-ts-swagger/issues) on GitHub and [submit a pull request](https://github.com/gersongoulart/gulp-swagger/pulls).
License
--------------------------
Gulp-TS-Swagger is 100% free and open-source, under the [MIT license](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-tools]: https://github.com/apigee-127/swagger-tools
[swagger-js-codegen]: https://github.com/wcandillon/swagger-js-codegen
[tv4]: https://github.com/geraintluff/tv4