egg(十三):使用egg-swagger-doc自动生成swagger接口管理

前言：

        后端java或者其他语言引入swagger是可以的，当然我们的egg中也是支持引入的，需要引入 egg-swagger-doc 。

实现效果：

 官方：入口

实现步骤：

1、安装

cnpm i egg-swagger-doc --save

2、打开 config/plugin.js ，加入下面内容

exports.swaggerdoc = {
  enable: true,
  package: 'egg-swagger-doc',
};

3、打开 config/config.default.js

   const config = exports = {};

    /**
   * 配置swagger
   * @property {String} dirScanner - 插件扫描的文档路径
   * @property {String} basePath - api前置路由
   * @property {Object} apiInfo - 可参考Swagger文档中的Info
   * @property {Array[String]} apiInfo - 可参考Swagger文档中的Info
   * @property {Array[String]} schemes - 访问地址协议http或者https
   * @property {Array[String]} consumes - contentType的集合
   * @property {Array[String]} produces - contentType的集合
   * @property {Object} securityDefinitions - 安全验证，具体参考swagger官方文档
   * @property {Boolean} enableSecurity - 是否使用安全验证
   * @property {Boolean} routeMap - 是否自动生成route
   * @property {Boolean} enable - swagger-ui是否可以访问
   */
  config.swaggerdoc = {
    dirScanner: './app/controller',
    apiInfo: {
      title: 'egg-swagger',
      description: 'swagger-ui for egg',
      version: '1.0.0',
    },
    schemes: ['http'],
    // consumes: ['application/json'],
    // produces: ['application/json'],
    securityDefinitions: {
      // apikey: {
      //   type: 'apiKey',
      //   name: 'clientkey',
      //   in: 'header',
      // },
      // oauth2: {
      //   type: 'oauth2',
      //   tokenUrl: 'http://petstore.swagger.io/oauth/dialog',
      //   flow: 'password',
      //   scopes: {
      //     'write:access_token': 'write access_token',
      //     'read:access_token': 'read access_token',
      //   },
      // },
    },
    // enableSecurity: false,
    // enableValidate: true,
    routerMap: true,
    enable: true,

  }

到这一步，配置文件已经到位了，现在得加入具体的路由注释了

4、添加模块

/**
 *  笔记路由note
 * @Controller 笔记
 */

5、添加具体方法注释，get请求

/**
 * @summary 获取笔记
 * @description 获取笔记
 * @Router get /setNoteList
 * @request query string username 账户名
 * @request query integer page 页码 默认 1
 * @request query integer pageSize 单页数量 默认 10
 * @Request header string authorization token值
* */
async getNoteList(){

}

注释含义：

• @controller 这个便变成一个tag
• @summary 简介
• @description 描述
• @router 就是请求地址
• @request 其实是swagger里面的parames，其中的authorize_login是定义中app/contract的一个object。翻译到swagger就是一个 object的引用。
• @response 响应，其中的baseResponse，同上。
• @consumes 提交到请求的数据格式(即带body的请求，例如post，有效其他无效），如果没有定义，则跟从配置文件设置。如果要多种选择，可以用空格分开，例如 @consumes html/text application/json。
• @product 同上。

6、post请求，注意，这里的参数body后面的 postNoteParams 是需要在contract中定义方法

/**
 * @summary 新增笔记
 * @description 新增笔记
 * @Router post /setNoteList
 * @request body postNoteParams *body
 * @Request header string authorization token值
 */
 async postNoteList(){

 }

7、新建contract文件夹，新建index.js

 index.js内容

module.exports = {
  //账户
  postAccountParams: {
    username: { type: 'string', required: false, description: '账户名' },
    password: { type: 'string', required: false, description: '密码' },
    role: { type: 'string', required: false, description: '权限' },
    phone: { type: 'string', required: false, format: /^1[34578]\d{9}$/, description: '电话' },
  },

}

8、将默认地址指向 swagger的地址，打开路由文件，如果不指向，地址是：http://localhost:7001/swagger-ui.html

/**
 * 路由配置
 * @param app
 */
module.exports = app => {
    const { router, controller, middleware } = app;


    //默认打开swagger
    router.redirect('/', '/swagger-ui.html',302);

}

9、打开页面，输入ip+端口号看效果，http://localhost:7001