Nucleic Photon Magnetizer

    gulp-ts-swagger

    1.0.0 • Public • Published

    gulp-ts-swagger v1.0.0


    Package gulp-ts-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

    Install

    npm install gulp-ts-swagger

    Usage

    Output fully parsed schema:

    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:

    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:

    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, 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.

    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 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

    Contributing

    I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.

    License

    Gulp-TS-Swagger is 100% free and open-source, under the MIT license. Use it however you want.

    Install

    npm i gulp-ts-swagger

    DownloadsWeekly Downloads

    1

    Version

    1.0.0

    License

    MIT

    Last publish

    Collaborators

    • kant2002