• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    迪恩网络公众号

gersongoulart/gulp-swagger: Gulp plugin that parses Swagger specs in JSON or YAM ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

gersongoulart/gulp-swagger

开源软件地址(OpenSource Url):

https://github.com/gersongoulart/gulp-swagger

开源编程语言(OpenSource Language):

JavaScript 62.9%

开源软件介绍(OpenSource Introduction):

gulp-swagger v1.0.0


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

Install

npm install gulp-swagger

Usage

Output 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',
      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:

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.

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.

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 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-Swagger is 100% free and open-source, under the MIT license. Use it however you want.




鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
ck86/gulp-bower-files: Build gulp.src() of your bower packages main files.发布时间:2022-06-21
下一篇:
ktmud/huggle: hugo + gulp发布时间:2022-06-21
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap