node环境 Express编写的后台接口如何结合swagger-ui【解决新版无法传输参数和自定义Authorization】

目录

1、安装

2、配置

3、编写注释

4、启动。

5、解决新版无法传输参数问题

5、如何在新版中header里使用Authorization参数传递token

---

最近学习使用Node构建后台接口服务，想着使用swagger-ui生成接口调试文档，查阅了网上相关资料，安装过程或者使用过程都写的不是太详细，对于新手特别是刚上手后台编程的新手有点不友好，所以我归纳一下我使用过程中涉及的一些方法。

1、安装

本文章中使用的是swagger-jsdoc和swagger-ui-express两个结合的形式进行生成swagger-ui接口文档。所以先安装一下这两个模块。

npm install --save-dev swagger-jsdoc
npm install --save-dev swagger-ui-express@2.0.8

 其中需要注意swagger-ui-express建议使用2.0.8版本，虽然这个模块的版本最新是V4.0.x。因为博主在使用过程中发现，大于2.0.8版本以上的版本，使用post发起请求是，body里的数据一直无法传过去，content-length也一直为0，而且在自定义header的时候也出现一些问题。楼主后面去GitHub上查了一下issues【点击跳转】，按照里面提出的解决方案我排查了，楼主的代码是没问题的，还是无法解决。最后把swagger-ui-express降级到2.0.8才可以正常使用。所以这里建议使用这个版本，当然你如果使用最新版本没问题的话也是可以的。

2、配置

配置swagger基本信息，以及指明接口文件存放的位置

const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');
const path = require('path');
const config = require('../config/default');

const options = {
    definition: {
        // swagger 采用的 openapi 版本 不用改
        openapi: '3.0.3',
        // swagger 页面基本信息 自由发挥
        info: {
            title: '后台管理系统接口',
            version: '创建时间：2020年3月27日',
        }
    },
    apis: [ path.join(__dirname, '../router/*.js') ]//这里指明接口路由存放的文件夹。楼主放在根路径的router下
}
const swaggerSpec = swaggerJSDoc(options)

module.exports = (app) => {
    if(config.ENV === 'Dev'){
        // 开放 swagger 相关接口，
        app.get('/swagger.json', function(req, res) {
            res.setHeader('Content-Type', 'application/json');
            res.send(swaggerSpec);
        });
        // 使用 swaggerSpec 生成 swagger 文档页面，并开放在指定路由
        app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
    }
}

3、编写注释

按照规范编写接口注释，具体规范可以查看这个网站【点击跳转】。这里需要特别注意的是：注意缩减和层次。否则构建出来会有问题。

// 这里给出楼主项目里的注释代码
// 定义参数
/**
 * @swagger
 * definition:
 *  noticeAddParams:
 *      description: 通知添加参数
 *      properties:
 *          title:
 *              type: string
 *          content:
 *              type: string
 *          endTime:
 *              type: string
 */
// 定义接口
/**
 * @swagger
 * /admin/notice/add:
 *   post:
 *     tags:
 *       - 管理员
 *     description: 通知添加
 *     consumes:
 *      - application/json
 *      - application/xml
 *     produces:
 *      - application/json
 *      - application/xml
 *     parameters:
 *       - name: Authorization
 *         in: header
 *         required: false
 *       - name: body
 *         in: body
 *         schema:
 *          $ref: '#/definitions/noticeAddParams'
 *     responses:
 *       200:
 *         description: 发布成功
 *       402:
 *          description: 信息填写不全
 *       403:
 *          description: 参数类型错误
 *
 */

4、启动。

启动node。访问IP:端口/api-docs。就可以看到自己写的接口了，也可以进行相关调试。

效果如下：

 

 

----------------------------------------------------分割线2020年4月27日14:39:18-------------------------------------------------------------

5、解决新版无法传输参数问题

今天有人回复了我在GitHub上发布的issues，传送门。swagger-ui-express大于2.0.8，需要使用openapi3.x规范去编写注释，小于2.0.8可以使用openapi2.x版本。3.x版本不兼容2.x。原因在于3.x中使用requestBody作为数据传输的主体，而2.x中使用的是paramters参数。下面给出新版注解：

/**
 * @swagger
 * /user/login:
 *   post:
 *     tags:
 *       - 用户
 *     description: 登录系统
 *     requestBody:
 *       required: true
 *       content:
 *          application/json:
 *              schema:
 *                  $ref: '#/definitions/loginInfo'
 *     responses:
 *       200:
 *         description: 登录成功，返回token和用户信息
 *
 */

给出旧版注释。

/**
 * @swagger
 * /user/login:
 *   post:
 *     tags:
 *       - 用户
 *     description: 登录系统
 *     consumes:
 *      - application/json
 *      - application/xml
 *     produces:
 *      - application/json
 *      - application/xml
 *     parameters:
 *       - name: body
 *         in: body
 *         required: true
 *         schema:
 *          $ref: "#/definitions/loginInfo"
 *     responses:
 *       200:
 *         description: 登录成功，返回token和用户信息
 *
 */

参照上述两个代码段，可以发现，新版的body需要放在requestBody里，而不是放在parameters。requestBody还有很多用法，大家可以参考传送门里的那个地址查看。

5、如何在新版中header里使用Authorization参数传递token

在openapi3.x规范中，Authorization这个参数是被OpenAPI占用的，如果你使用该参数作为请求头，你会发现你触发请求的时候，Authorization参数并不会被携带在header中，如果不用这个参数就可以携带。那我如果一定要使用这个参数作为token的携带参数怎么办？

先给出issues上的答案。传送门1、传送门2。也许你会看的云里雾里的，下面我给出我的解决不走。

1）、首先使用components注解声明全局的securitySchemes。具体参数在传送门2中有详细解释。

/**
 * @swagger
 * components:
 *  securitySchemes:
 *   ApiKeyAuth: // 名称
 *     type: apiKey // 类型
 *     in: header // 位置
 *     name: Authorization // 参数
 */

2）、去除原先parameters中header的声明。如果只声明Authorization这个参数的话，就把声明去掉，如果还有其他的参数，那就仅去掉Authorization。

3）、引用这些安全声明。你可以全局引用也可以在API注解中引用。推荐使用后者，可以按照自己的需求自行控制。

/**
 * @swagger
 * /user/login:
 *   post:
 *     tags:
 *       - 用户
 *     description: 登录系统
 *     security:
 *      - ApiKeyAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *          application/json:
 *              schema:
 *                  $ref: '#/definitions/loginInfo'
 *     responses:
 *       200:
 *         description: 登录成功，返回token和用户信息
 *
 */

4）、声明完之后，运行项目。你会发现，添加过security的api后面有跟着一个锁，且在文档右上方也出现了一个按钮。

5）、点击右上方按钮或者api后面的锁，他会弹出一个框要求你输入Authorization值。按照提示输入后，点击确认，锁图表从开状态变成闭合状态，这时候你在触发你的api请求，你会发现，swagger自己加上了刚才你输入的Authorization值。

从上图你可以看到，在parameters中，我并没有添加Authorization这个header字段，而是交给OAS3内置的安全认证去处理。当然你如果不用这个参数，那就非常简单了，处理如下。

/**
 * @swagger
 * /admin/notice/add:
 *   post:
 *     tags:
 *       - 管理员
 *     description: 通知添加
 *     parameters:
 *      - in: header
 *        name: x-http-token
 *     requestBody:
 *       required: true
 *       content:
 *          application/json:
 *              schema:
 *                 $ref: '#/definitions/noticeAddParams'
 *     responses:
 *       200:
 *         description: 获取成功
 *
 */