jsonma/swagger-egg

Eggjs Swagger-UI API文档自动生成插件（如果喜欢请点赞支持）。Egg swagger documentation generator（welcome to star this project）.

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

$ 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

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

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.

// {app_root}/config/config.default.js
exports.swaggerEgg = {
  schema: {
    path: '/app/schema', // JSON Schema directory
  },
  swagger: {
    info: {
      title: 'Test swagger',
      description: 'Testing the Fastify swagger API',
      version: '0.1.0'
    },
    externalDocs: {
      url: 'https://swagger.io',
      description: 'Find more info here'
    },
    host: '127.0.0.1:7001', // should be egg server's host, otherwise result in cross origin error
    schemes: ['http', 'https'],
    consumes: ['application/json'],
    produces: ['application/json'],
    tags: [
      { name: 'user', description: 'User related end-points' }
    ],
    securityDefinitions: {
      api_key: {
        type: 'apiKey', // basic/apiKey/oauth2
        name: 'Authorization', // selfdefined parameter, usually use 'Authorization'
        in: 'header', // query or header, usually use 'header'
      },
      github_auth: {
        type: 'oauth2',
        authorizationUrl: 'http://swagger.io/api/oauth/dialog',
        flow: 'implicit',
        scopes: {
          'write:homes': 'modify home info',
          'read:homes': 'read home info',
        },
      },
    },
    security: [
      {
        api_key: [], // select 'api_key' to security(defined in `securityDefinitions`)
      },
    ], // Cacution: security is array type
    typescriptJsonSchema: false, // use typescript json schema. (see: https://github.com/YousefED/typescript-json-schema)
  }
};

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

Grammer

#swagger-api

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

  /**
   * #swagger-api
   *
   * @function index
   */
  async index() {
    this.ctx.body = 'hi, #swagger-api example'
  }

@function {Name}

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

  /**
   * Function example #swagger-api
   *
   * @function index
   */
  async index() {
    this.ctx.body = 'hi, function example'
  }

@summary {functionSummary}

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

  /**
   * Function example #swagger-api
   *
   * @function index
   * @summary This is function's summary.
   */
  async index() {
    this.ctx.body = 'hi, summary example'
  }

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

  /**
   * Tags example #swagger-api
   *
   * @function index
   * @description #tags user admin
   */
  async index() {
    this.ctx.body = 'hi, tags example'
  }

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

#produces is used for declaring API response mimetype.

NOTE: Multiple mimetypes should be separated by whitespace.

  /**
   * Produces example #swagger-api
   *
   * @function index
   * @description #produces application/json
   */
  async index() {
    this.ctx.body = 'hi, produces example'
  }

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

#consumes is used for declaring API request mimetype.

NOTE: Multiple mimetypes should be separated by whitespace.

  /**
   * Consumes example #swagger-api
   *
   * @function index
   * @description #consumes application/json
   */
  async index() {
    this.ctx.body = 'hi, consumes example'
  }

@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'.

  /**
   * Parameters example #swagger-api
   *
   * @function index
   * @description #parameters id path schema.id true - id parameter
   */
  async index() {
    this.ctx.body = 'hi, parameters example'
  }

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

#responses is used for declaring api response info.

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

  /**
   * Responses example #swagger-api
   *
   * @function index
   * @description #responses schema.user - user responses
   */
  async index() {
    this.ctx.body = 'hi, responses example'
  }

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.

// {app_root}/app/schema/users.js

module.exports = {
  type: 'object',
  properties: {
    id: {
      type: 'string',
      description: 'user id'
    },
    name: {
      type: 'string',
      description: 'user name'
    },
    age: {
      type: 'number',
      description: 'user age'
    },
  },
  required: [ 'id', 'name', 'age' ],
  additionalProperties: false,
};

Controller Example

// {app_root}/app/controller/users.js

const Controller = require('egg').Controller;

class UserController extends Controller {

  /**
   * Index action #swagger-api
   *
   * @function index
   * @memberof UserController
   * @description #tags user
   * @description #produces application/json
   * @description #parameters index query schema.definitions.index true - parameter index
   * @description #responses 200 schema.user - index response
   */
  async index() {
    this.ctx.body = 'hi, index action' + this.app.plugins.swaggerEgg.name;
  }

  /**
   * New action #swagger-api
   *
   * @function new
   * @memberof UserController
   * @description #tags user
   * @description #consumes application/x-www-form-urlencoded
   * @description #produces application/json
   * @description #parameters userInfo body schema.user true - parameter userInfo
   * @description #responses 200 schema.user - new response
   */
  async new() {
    this.ctx.body = 'hi, new action' + this.app.plugins.swaggerEgg.name;
  }

  /**
   * Show action #swagger-api
   *
   * @function show
   * @memberof UserController
   * @description #tags user
   * @description #produces application/json
   * @description #parameters id path schema.definitions.id true - parameter id
   * @description #responses 200 schema.user - show response
   */
  async show() {
    this.ctx.body = 'hi, show action' + this.app.plugins.swaggerEgg.name;
  }

  /**
   * Edit action #swagger-api
   *
   * @function edit
   * @memberof UserController
   * @description #tags user
   * @description #consumes application/x-www-form-urlencoded
   * @description #produces application/json
   * @description #parameters id path schema.definitions.id true - parameter id
   * @description #parameters userInfo body schema.user true - parameter userInfo
   * @description #responses 200 schema.user - edit response
   */
  async edit() {
    this.ctx.body = 'hi, edit action ' + this.app.plugins.swaggerEgg.name;
  }

  /**
   * Create action #swagger-api
   *
   * @function create
   * @memberof UserController
   * @description #tags user
   * @description #consumes application/x-www-form-urlencoded
   * @description #produces application/json
   * @description #parameters userInfo body schema.user true - parameter userInfo
   * @description #responses 200 schema.user - create response
   */
  async create() {
    this.ctx.body = 'hi, create action ' + this.app.plugins.swaggerEgg.name;
  }

  /**
   * Update action #swagger-api
   *
   * @function update
   * @memberof UserController
   * @description #tags user
   * @description #consumes application/x-www-form-urlencoded
   * @description #produces application/json
   * @description #parameters id path schema.definitions.id true - parameter id
   * @description #parameters userInfo body schema.user true - parameter userInfo
   * @description #responses 200 schema.user - update response
   */
  async update() {
    this.ctx.body = 'hi, update action ' + this.app.plugins.swaggerEgg.name;
  }

  /**
   * Destory action #swagger-api
   *
   * @function destory
   * @memberof UserController
   * @description #tags user
   * @description #consumes application/json
   * @description #produces application/json
   * @description #parameters id path schema.definitions.id false - parameter id
   * @description #responses 200 schema.user - destory response
   */
  async destory() {
    this.ctx.body = 'hi, destory action ' + this.app.plugins.swaggerEgg.name;
  }
}

module.exports = UserController;

Questions & Suggestions

Please open an issue here.

License

MIT

swagger-egg's Issues

swagger-egg/example/egg-swagger-example/ 运行效果没有路由接口信息

npm run dev之后访问index.html,页面能出来,但是没有显示定义的接口API文档

多个路由文件怎么写？我的一直显示不了

使用egg-router-plus后，提示错误

[swagger-egg] [egg-core] load file: xxx\app\router.js, error: ENOENT: no such file or directory, open 'xxx\app\router.js'

额外写一个HotelController，无法正常显示，只有在HomeController中能显示

我想再写一个controller，但是调半天一直显示不出来，不知道什么原因。

git地址：[email protected]:oliver-lou/swagger-egg.git

请示是不是不支持tegg的写法

https://github.com/eggjs/tegg

报错的大概信息是：
error: ENOENT: no such file or directory, open '/Users/xxxx/Documents/my-gitlab-project/egg-project-example/hello-tegg/app/router.ts

tegg 的写法是将路由放在 controller里面了，类似midway 写法了

注意：关于带短横线或下划线的文件名问题

注意： 若controller、schema文件名中包含短横线："-" 或者下划线："_"，为了保持与Eggjs特性一致，文件名将会自动转换成驼峰命形式。

如何全局设置鉴权变量？

大部分接口都是需要token等头信息验证才能访问的，该如何设置呢？

example 都跑不起来啊

Home下面什么都么有啊

`package-lock.json` 中存在无法解析的域名 npm.corp.kuaishou.com

估计是内网域名。导致按照 package-lock.json 无法安装 node_modules。

建议暴露ts编译出的 `schemaObject` 以便复用于参数校验

当配置 typescriptJsonSchema: true 时， app/schema/**/*.ts 中会编译成 schemaObject ，虽然可以在注释中引用 schemaObject 进行声明，但看起来没法在 app/controller/**/*.ts 的代码中引用 schemaObject 。

建议插件把 schemaObject 挂载到 app 或 ctx ，以便复用于 ctx.valudate(rules, data) 的规则中，否则需要在 rules 中重复声明参数类型等信息。

注意：关于如何定义示例(example)的问题

注意：parameter（仅当类型为body时）及response中可以通过schema的example字段来定义示例！

例如：

请问想在apifox里配置出post请求，参数取json，controller里应该怎么配置呢

我想在apifox里配置post请求，一般我的post请求都是用的json格式，不是x-www-form-urlencoded的格式，现在我在controller里配置
* @description #parameters userid formData string true - 用户id
导入到Apifox以后变成了x-www-form-urlencoded的参数，这样的参数拿到格式不对，请教一下怎么配置

有时候服务起不来http://127.0.0.1:7001/public/index.html

TS应用中默认的 `yarn start` 命令启动报错

问题复现步骤

eggjs新建 TS 项目。 [email protected], [email protected]

正常写 app/schema/definitions.ts 。

先 yarn run tsc ，再 yarn start 。

问题表现

[egg-scripts] File '<egg-app>/app/schema/definitions.js' is a JavaScript file. Did you mean to enable the 'allowJs' option?
[egg-scripts]   The file is in the program because:
[egg-scripts]     Root file specified for compilation

奇怪为什么 app/schema/definitions.js 会成为 root file。

在 egg-scripts 中断点拿到的此异常的信息 error TS6504: File '*.js' is a JavaScript file. Did you mean to enable the 'allowJs' option?

尝试解决未果

eggjs为TS应用生成的 tsconfig.json 中为 compilerOptions.allowJs: false ，不确定eggjs是否对此强依赖。如果改成 true，那么在 yarn run tsc 时会报错，或许是强依赖，没继续深入研究。

error TS2347: Untyped function calls may not accept type arguments.

error TS2339: Property 'mongoose' does not exist on type 'MockApplication'.
const invalidAccountAppId = (new app.mongoose.Types.ObjectId()).toString();

支持 ts 项目上有什么难点吗？

目前我在项目中用的是 ts 来开发，目前支持 ts 项目上有什么问题吗？

解析不出 controller action

问题表现

解析不出 controller action

复现数据示例

// app/router.ts
router
  .get(
    'path/to/foo',
    middlewareBar,
    // 注意末尾有逗号
    app.controller.foo.action,
  )

根本原因

34, 35行解析得太理想化了，建议在单元测试中补充边界case。

有多个in body的#parameters 时@rtk-query/codegen-openapi报错

问题表现

有多个 in body 的 #parameters 时 ，将所生成的 app/public/swagger/*.json 返回给前端用于 @rtk-query/codegen-openapi ，会报错 has multiple requestBodies

根本原因

按照OpenAPI 2.0示例，in body的 parameters 只有1个，用 properties 表示其中不同的参数。
但 swagger-egg 会生成多个 in body的 parameters

#responses 不写 Description 会报错

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

#responses 不写 Description 会报错

问题表现：
2022-03-29 16:26:30,117 ERROR 167275 [swagger-egg] Cannot read properties of null (reading 'pop')
抛出异常导致中断后续流程，解析不完整。

根本原因：
71行的正则写得太死，认为总是会存在 Description 。

另外， responnseParser 单词拼写错误。

controller文件名带有'-'生成不了api文档

// router.js
router.resources('xxx-test', '/api/xxx-test', controller.xxxTest);

// controller/xxx-test.js
class XxxTestController extends Controller {
  /**
   * #swagger-api
   * @function index
   * @summary 查询
   * @description #tags xxx-test
   */
  async index() {
      this.ctx.body = 'select!!!';
  }

默认路径问题

默认路径是这样的，http://127.0.0.1:7001/swagger-ui.html
但是我想配置如，http://127.0.0.1:7001/docs-api/swagger-ui.html

配置controller注释时，parameterSchema中，目前能否支持一些常用类型的配置？

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

目前在controller中，是否可以直接在{ParameterSchema}处 直接配置参数的类型，比如常用的 string ,number,object,file 等？

例如：
*@description#parameters obj query {number} false - obj

如何设置参数的默认值？

schema如何支持array类型，则其过元素为object

schema如何支持array类型，则其下元素为object

路由信息解析不出来

因为 swagger-egg 是自己用正则解析 app/router.ts 文件内容，获取路由信息。
参考 node_modules/swagger-egg/lib/router_loader.js 中的 getRouter() 方法。

导致很多情况解析不出来，比如

• 使用 egg-router-plus
• 使用 `'router-name'``
• 'path-match' 不是字符串字面量，而是一个表达式或变量

router.verb('path-match', app.controller.action);
router.verb('router-name', 'path-match', app.controller.action);
router.verb('path-match', middleware1, ..., middlewareN, app.controller.action);
router.verb('router-name', 'path-match', middleware1, ..., middlewareN, app.controller.action);

destory 写错了 应该是 destroy

destory 写错了 应该是 destroy