npm install swagger-ui-express swagger-jsdoc -S

const path = require('path')
const express = require('express')
const swaggerUI = require('swagger-ui-express')
const swaggerDoc = require('swagger-jsdoc')
//配置swagger-jsdoc
  const options = {
    definition: {
      openapi: '3.0.0',
      info: {
        title: 'api',
        version: '1.0.0',
        description: `小程序+管理后臺共用接口api`
      }
    },
    // 去哪個路由下收集 swagger 注釋
    apis: [path.join(__dirname,'../../routes/*.js')]
  }
  var swaggerJson = function (req, res) {
    res.setHeader('Content-Type', 'application/json');
    res.send(swaggerSpec);
  }
  const swaggerSpec = swaggerDoc(options)
  
  var swaggerInstall = function(app) {
    if (!app){
      app = express()
    }
    // 開放相關接口，
    app.get('/swagger.json', swaggerJson);
    // 使用 swaggerSpec 生成 swagger 文檔頁面，并開放在指定路由
    app.use('/swagger', swaggerUI.serve, swaggerUI.setup(swaggerSpec));
  }
  module.exports = swaggerInstall 

// 使用swagger API 文檔
var swaggerInstall = require('./utils/swagger')
swaggerInstall(app)

/**,
 * @swagger
 * /api/addExam:
 *    post:
 *      tags:
 *      - 測試
 *      summary: 提交考試答案
 *      produces:
 *      - application/json
 *      parameters:
 *      - name: name
 *        in: query
 *        description: 姓名
 *        required: false
 *        type: integer
 *        maximum:
 *        minimum: 1
 *        format:
 *      - name: phone
 *        in: query
 *        description: 電話
 *        required: false
 *        type: integer
 *        maximum:
 *        minimum: 1
 *        format:
 *      responses:
 *        200:
 *          description: successful operation
 *          schema:
 *            ref: #/definitions/Order
 *        400:
 *          description: Invalid ID supplied
 *        404:
 *          description: Order not found
 * */

npm install egg-swagger-doc --save

/* /config/config.default.js */
/ egg-swagger-doc 配置信息。
exports.swaggerdoc = {
    dirScanner: './app/controller', // 配置自動掃描的控制器路徑。
    // 接口文檔的標題，描述或其它。
    apiInfo: {
        title: 'NAPI',  // 接口文檔的標題。
        description: 'swagger-ui for NAPI document.',   // 接口文檔描述。
        version: '1.0.0',   // 接口文檔版本。
    },
    schemes: ['http', 'https'], // 配置支持的協議。
    consumes: ['application/json'], // 指定處理請求的提交內容類型（Content-Type），例如application/json, text/html。
    produces: ['application/json'], // 指定返回的內容類型，僅當request請求頭中的(Accept)類型中包含該指定類型才返回。
    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,  // 是否啟用授權，默認 false（不啟用）。
    // enableValidate: true,    // 是否啟用參數校驗，默認 true（啟用）。
    routerMap: true,    // 是否啟用自動生成路由，默認 true (啟用)。
    enable: true,   // 默認 true (啟用)。
};

* /config/plugin.js */
'use strict';
 
// 配置 egg-swagger-doc 插件信息。
exports.swaggerdoc = {
    enable: true,   // 是否啟用。
    package: 'egg-swagger-doc', // 指定包名稱。
};

/* /app/contract/format.js */
//自動文檔約定
module.exports = {
    JsonBody: { // 這個名字對應上面 Controller 注釋的@response 的 JsonBody。
        result: { type: 'string' }, // 服務器返回的數據。
    },
};

'use strict';
 
const BaseController = require("../base");
/**
* @controller 測試控制器 注釋必寫，swagger-doc是根據這段注釋來生成接口的 ）。
*/
class HomeController extends BaseController {
   /**  （ 注釋必寫，swagger-doc是根據這段注釋來生成接口詳細信息的 ）。
    * @summary 根據ID查詢信息。
    * @description 根據ID查詢信息。
    * @router get /api （ get 表示設置請求為 get 請求，最后的 selectById 對應下面的 selectById 方法 ）。
    * @request query integer Id 需要去查新的ID。（ get 對應 query 請求，請求值設定為 integer 純數字類型，ID 為請求的字段，注意大小寫，和下面的方法要一一對應，不然會報錯 ）。
    * @response 200 JsonBody 返回結果。（ 對應 contract 里面的驗證屬性，下面會提到 。）
    */
  async index() {
    const { ctx } = this;
   
    let result = await this.app.mysql.query(
      'select * from user'
      );
      this.notFound()
  }
 
  async v1(){
    const { ctx } = this;
    ctx.body = "我是v1自動路由";
  }
}
 
module.exports = HomeController;