一键配置swagger在node.js下express中的使用

项目开发中前后端交互比较多，其中最重要的就是接口的交接，常用的接口交接方式就是用的Excel、doc，接口查看不是特别直观和美观，今天介绍一个可以在web界面显示API的方式。

1. 先在任意文件下新建一个文件swagger.js如我自己是在utils文件夹下新建swagger文件夹里面有一个index.js文件代码如下图所示
2. 【特别注意】修改代码中options 中的 apis，需要指定到你的swagger注释的路径，我这里是routes/里面的所有文件，每个人各不相同
3. 在app.js中引用该文件调用swaggerInstall方法

var swaggerInstall = require('./utils/swagger')
swaggerInstall(app)
或者直接调用如下代码
require('./utils/swagger')(app)

index.js

var path = require('path');
var express = require('express');
var swaggerUi = require('swagger-ui-express')
var swaggerJSDoc = require('swagger-jsdoc')
// 配置 swagger-jsdoc
const options = {
  definition: {
    // 采用的 openapi 版本 不用改
    openapi: '3.0.0',
    // 页面基本信息 自由发挥
    info: {
      title: 'Sunny Server',
      version: '1.0.0',
    }, 
  },
  // 去哪个路由下收集 swagger 注释
  apis: [path.join(__dirname, '../../routes/**/*.js')]
}
var swaggerJson = function (req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(swaggerSpec);
}
const swaggerSpec = swaggerJSDoc(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 在js 中的注释如下所示，可在配置的路径下任意js地方注释，swagger-jsdoc会遍历查找

/**,
 * @swagger
 * /test1:
 *    get:
 *      tags:
 *      - sunny
 *      summary: 测试
 *      description: 测试
 *      operationId: test1
 *      produces:
 *      - application/json
 *      parameters:
 *      - name: current
 *        in: query
 *        description:
 *        required: false
 *        type: integer
 *        maximum:
 *        minimum: 1
 *        format:
 *      - name: size
 *        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
 * */