swagger-egg

中文文档

An egg-swagger plugin (support Typescript) for serving a Swagger UI, params should follow JSON Schema specification (recommend use Ajv)，using Swagger (OpenAPI v2) schemas automatically generated from your controller JSDoc comments.

CAUTION: Require Node.js 10.x or higher!

Install

1$ npm i swagger-egg --save

Usage

Enable this plugin, visting index.html under static resource directory and you will get the Swagger UI page. Visiting http://localhost:7001/public/index.html to get the default Swagger-UI page. Project Example:

• JS Example
• TS Example
• TS-Json-Schema Example

1// {app_root}/config/plugin.js
2exports.swaggerEgg = {
3  enable: true,
4  package: "swagger-egg",
5};

Configuration

• swagger.info is optional and will be generated from your application's package.json if not exist.
• swagger.tags is required if controller's JSDoc comments used tags.

1// {app_root}/config/config.default.js
2exports.swaggerEgg = {
3  schema: {
4    path: '/app/schema', // JSON Schema directory
5  },
6  swagger: {
7    info: {
8      title: 'Test swagger',
9      description: 'Testing the Fastify swagger API',
10      version: '0.1.0'
11    },
12    externalDocs: {
13      url: 'https://swagger.io',
14      description: 'Find more info here'
15    },
16    host: '127.0.0.1:7001', // should be egg server's host, otherwise result in cross origin error
17    schemes: ['http', 'https'],
18    consumes: ['application/json'],
19    produces: ['application/json'],
20    tags: [
21      { name: 'user', description: 'User related end-points' }
22    ],
23    securityDefinitions: {
24      api_key: {
25        type: 'apiKey', // basic/apiKey/oauth2
26        name: 'Authorization', // selfdefined parameter, usually use 'Authorization'
27        in: 'header', // query or header, usually use 'header'
28      },
29      github_auth: {
30        type: 'oauth2',
31        authorizationUrl: 'http://swagger.io/api/oauth/dialog',
32        flow: 'implicit',
33        scopes: {
34          'write:homes': 'modify home info',
35          'read:homes': 'read home info',
36        },
37      },
38    },
39    security: [
40      {
41        api_key: [], // select 'api_key' to security(defined in `securityDefinitions`)
42      },
43    ], // Cacution: security is array type
44    typescriptJsonSchema: false, // use typescript json schema. (see: https://github.com/YousefED/typescript-json-schema)
45  }
46};

see config/config.default.js for more detail.

Grammer

#swagger-api

#swagger-api in front of JSDoc comments is required!

1  /**
2   * #swagger-api
3   *
4   * @function index
5   */
6  async index() {
7    this.ctx.body = 'hi, #swagger-api example'
8  }

@function {Name}

The JSDoc @function is required, which is used to search router info from app/router.js.

1  /**
2   * Function example #swagger-api
3   *
4   * @function index
5   */
6  async index() {
7    this.ctx.body = 'hi, function example'
8  }

@summary {functionSummary}

The JSDoc @summary is used to describe the function's summary.

1  /**
2   * Function example #swagger-api
3   *
4   * @function index
5   * @summary This is function's summary.
6   */
7  async index() {
8    this.ctx.body = 'hi, summary example'
9  }

@description #tags {Tag1} {Tag2} ...

#tags is used for logical grouping of operations by resources or any other qualifier.

NOTE: Multiple tags should be separated by whitespace.

1  /**
2   * Tags example #swagger-api
3   *
4   * @function index
5   * @description #tags user admin
6   */
7  async index() {
8    this.ctx.body = 'hi, tags example'
9  }

@description #produces {Mimetype1} {Mimetype2} ...

#produces is used for declaring API response mimetype.

NOTE: Multiple mimetypes should be separated by whitespace.

1  /**
2   * Produces example #swagger-api
3   *
4   * @function index
5   * @description #produces application/json
6   */
7  async index() {
8    this.ctx.body = 'hi, produces example'
9  }

@description #consumes {Mimetype1} {Mimetype1} ...

#consumes is used for declaring API request mimetype.

NOTE: Multiple mimetypes should be separated by whitespace.

1  /**
2   * Consumes example #swagger-api
3   *
4   * @function index
5   * @description #consumes application/json
6   */
7  async index() {
8    this.ctx.body = 'hi, consumes example'
9  }

@description #parameters {PrameterName} {In} {ParameterSchema|Type} {Required} - {Description}

#parameters is used for declaring api request parameters.

NOTE: Description is separated by - and others are separated by whitespace.

NOTE:

• In should be within 'query', 'header', 'path', 'formData', 'body' according to Swagger specification.
• Required should be boolean type.
• Type should be within 'string', 'number', 'integer', 'boolean', 'array', 'file'.

1  /**
2   * Parameters example #swagger-api
3   *
4   * @function index
5   * @description #parameters id path schema.id true - id parameter
6   */
7  async index() {
8    this.ctx.body = 'hi, parameters example'
9  }

@description #responses {HttpStatus} {ResponseSchema} - {Description}

#responses is used for declaring api response info.

NOTE: Description is separated by - and others are separated by whitespace.

1  /**
2   * Responses example #swagger-api
3   *
4   * @function index
5   * @description #responses schema.user - user responses
6   */
7  async index() {
8    this.ctx.body = 'hi, responses example'
9  }

Schema Example

Schema should follow the JSON Schema specification. You can use Ajv to validate it.

Change swaggerEgg.schema.path field in config file if you want to redefine it.

1// {app_root}/app/schema/users.js
2
3module.exports = {
4  type: 'object',
5  properties: {
6    id: {
7      type: 'string',
8      description: 'user id'
9    },
10    name: {
11      type: 'string',
12      description: 'user name'
13    },
14    age: {
15      type: 'number',
16      description: 'user age'
17    },
18  },
19  required: [ 'id', 'name', 'age' ],
20  additionalProperties: false,
21};

Controller Example

1// {app_root}/app/controller/users.js
2
3const Controller = require('egg').Controller;
4
5class UserController extends Controller {
6
7  /**
8   * Index action #swagger-api
9   *
10   * @function index
11   * @memberof UserController
12   * @description #tags user
13   * @description #produces application/json
14   * @description #parameters index query schema.definitions.index true - parameter index
15   * @description #responses 200 schema.user - index response
16   */
17  async index() {
18    this.ctx.body = 'hi, index action' + this.app.plugins.swaggerEgg.name;
19  }
20
21  /**
22   * New action #swagger-api
23   *
24   * @function new
25   * @memberof UserController
26   * @description #tags user
27   * @description #consumes application/x-www-form-urlencoded
28   * @description #produces application/json
29   * @description #parameters userInfo body schema.user true - parameter userInfo
30   * @description #responses 200 schema.user - new response
31   */
32  async new() {
33    this.ctx.body = 'hi, new action' + this.app.plugins.swaggerEgg.name;
34  }
35
36  /**
37   * Show action #swagger-api
38   *
39   * @function show
40   * @memberof UserController
41   * @description #tags user
42   * @description #produces application/json
43   * @description #parameters id path schema.definitions.id true - parameter id
44   * @description #responses 200 schema.user - show response
45   */
46  async show() {
47    this.ctx.body = 'hi, show action' + this.app.plugins.swaggerEgg.name;
48  }
49
50  /**
51   * Edit action #swagger-api
52   *
53   * @function edit
54   * @memberof UserController
55   * @description #tags user
56   * @description #consumes application/x-www-form-urlencoded
57   * @description #produces application/json
58   * @description #parameters id path schema.definitions.id true - parameter id
59   * @description #parameters userInfo body schema.user true - parameter userInfo
60   * @description #responses 200 schema.user - edit response
61   */
62  async edit() {
63    this.ctx.body = 'hi, edit action ' + this.app.plugins.swaggerEgg.name;
64  }
65
66  /**
67   * Create action #swagger-api
68   *
69   * @function create
70   * @memberof UserController
71   * @description #tags user
72   * @description #consumes application/x-www-form-urlencoded
73   * @description #produces application/json
74   * @description #parameters userInfo body schema.user true - parameter userInfo
75   * @description #responses 200 schema.user - create response
76   */
77  async create() {
78    this.ctx.body = 'hi, create action ' + this.app.plugins.swaggerEgg.name;
79  }
80
81  /**
82   * Update action #swagger-api
83   *
84   * @function update
85   * @memberof UserController
86   * @description #tags user
87   * @description #consumes application/x-www-form-urlencoded
88   * @description #produces application/json
89   * @description #parameters id path schema.definitions.id true - parameter id
90   * @description #parameters userInfo body schema.user true - parameter userInfo
91   * @description #responses 200 schema.user - update response
92   */
93  async update() {
94    this.ctx.body = 'hi, update action ' + this.app.plugins.swaggerEgg.name;
95  }
96
97  /**
98   * Destory action #swagger-api
99   *
100   * @function destory
101   * @memberof UserController
102   * @description #tags user
103   * @description #consumes application/json
104   * @description #produces application/json
105   * @description #parameters id path schema.definitions.id false - parameter id
106   * @description #responses 200 schema.user - destory response
107   */
108  async destory() {
109    this.ctx.body = 'hi, destory action ' + this.app.plugins.swaggerEgg.name;
110  }
111}
112
113module.exports = UserController;
114

Questions & Suggestions

Please open an issue here.

License

MIT