从0到1 express 安装swagger

1、什么是swagger

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器,在我们后端开发中，swagger可以可视化的提供测试服务。

2、从0到1引入swagger

首先提供swagger的官网地址：https://swagger.io/

工程中需要引入的swagger-jsdoc 官方文档地址: https://github.com/Surnet/swagger-jsdoc

2.1新建express工程

express -e swagger-test
1

修改运行端口号，于app.js中新增3000端口号

app.listen(3000, () => {
  console.log("sever in running");
});
1
2
3

2.2引入相关swagger依赖包和文件

安装swagger需要的相关依赖包swagger-ui-express 和 swagger-jsdoc ：

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

接下来初始化swagger并配置swagger-jsdoc，为了工程的模块性，我们将swagger抽离放置于utils文件夹下面,在工程的utils/swaggers(需要手动新建文件夹)目录下新建index.js文件

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;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

随后在app.js中全局注册swagger

var swaggerInstall = require("./utils/swagger");
swaggerInstall(app);
1
2

2.3使用swagger注释来形成接口文档

例：新增test 接口来验证swagger是否正常启用

/**,
 * @swagger
 * /test:
 *    get:
 *      tags:
 *      - 小程序端
 *      summary: 提交考试答案
 *      produces:
 *      - application/json
 *      responses:
 *        200:
 *          description: successful operation
 *          schema:
 *            ref: #/definitions/Order
 *        400:
 *          description: Invalid ID supplied
 *        404:
 *          description: Order not found
 * */
router.get("/test", function (req, res, next) {
  res.send("get 提交");
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

运行项目:

node app.js (或者nodemon app.js 得自己安装nodemon)
1

打开浏览器输入

http://localhost:3000/swagger/#/
1

(注：自定义可以修改原utils/swaggers/index.js中的路径)

常见请求注释模板：

/**,
 * @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
 * */

/**,
 * @swagger
 * /user/login:
    get:
      tags:
        - user
      summary: Logs user into the system
      description: ''
      operationId: loginUser
      parameters:
        - name: username
          in: query
          description: The user name for login
          required: false
          schema:
            type: string
        - name: password
          in: query
          description: The password for login in clear text
          required: false
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          headers:
            X-Rate-Limit:
              description: calls per hour allowed by the user
              schema:
                type: integer
                format: int32
            X-Expires-After:
              description: date in UTC when token expires
              schema:
                type: string
                format: date-time
          content:
            application/xml:
              schema:
                type: string
            application/json:
              schema:
                type: string
        '400':
          description: Invalid username/password supplied
 * */
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

详细的注释模板请浏览https://editor.swagger.io/ 进行学习