express整合swagger

参考网址:

1. https://editor.swagger.io/
2. https://swagger.io/docs/specification/about/

项目代码

效果图:

加载swagger配置

访问/api/admin/swagger.html, 就会加载对应的swagger配置

const express = require("express");
const app = express();
var swaggerUi = require("swagger-ui-express");
const adminDocument = require("./swaggerJSON/admin.json");
app.use("/api/admin/swagger.html", swaggerUi.serve, swaggerUi.setup(adminDocument)); 

/* 获取所有用户 */
app.get("/api/getAllUser", (req, res) => {
  const sql = "select * from admin";
  query(sql, [], (err, data) => {
    res.status(200);
    res.json({
      data: data,
      msg: "获取成功",
      code: "200",
    });
  });
});
... 
.......

swagger相关配置 (./swaggerJSON/admin.json)

提取主要部分, 路由匹配对应的注解

  "paths": {
   // 匹配路由, 加载对应的配置
    "/api/getAllUser": { 
    // =======================get请求=================
      "get": {
        "tags": ["用户模块"],
        "summary": "获取所有用户",
        "responses": {
          "200": {
            "description": "successful operation",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Admin"
              }
            }
          },
          "400": {
            "description": "Invalid status value"
          }
        }
      }
    },
    "/api/getUserByUsername/{username}": {
     // =======================get请求, 有参数的=================
      "get": {
        "tags": ["用户模块"],
        "summary": "根据用户名获取所有用户",
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "description": "用户名",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Admin"
              }
            }
          },
          "400": {
            "description": "Invalid status value"
          }
        }
      }
    },
    "/api/createAdmin": {
     // =======================post请求, 有请求体的=================
      "post": {
        "tags": ["用户模块"],
        "summary": "新增用户",
        "consumes": ["application/json", "application/xml"],
        "produces": ["application/xml", "application/json"],
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "description": "新增用户所需要的字段",
            "required": true,
            "schema": {
              "$ref": "#/definitions/Admin"
            }
          }
        ],
        "responses": {
          "405": {
            "description": "Invalid input"
          }
        }
      }
    },
    "/api/user/{id}": {
    // =======================delete请求, 有请求参数=================
      "delete": {
        "tags": ["用户模块"],
        "summary": "删除用户",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "用户id",
            "required": true,
            "type": "integer"
          }
        ],
        "responses": {
          "405": {
            "description": "Invalid input"
          }
        }
      },
      // =======================put请求, 有请求参数=================
      "put": {
        "tags": ["用户模块"],
        "summary": "修改用户",
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "description": "修改用户所需要的字段",
            "required": ["id", "password", "username"],
            "schema": {
              "$ref": "#/definitions/Admin"
            }
          }
        ],
        "responses": {
          "405": {
            "description": "Invalid input"
          }
        }
      }
    }
  },
  "definitions": {
    "Admin": {
      "type": "object",
      "required": ["username", "password"],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "username": {
          "type": "string",
          "example": "chenjiang"
        },
        "password": {
          "type": "string",
          "example": "password"
        }
      }
    }
  }
}