简介

Swagger（OpenAPI 规范）可以通过多种来方式定义API文档，详情介绍Swagger请查看我的另外一篇文章，此处不再赘述

传送门

swagger-jsdoc

swagger-jsdoc 是一个流行的工具，它允许你通过 JSDoc 风格的注释来描述你的 Node.js 代码中的 API，并自动生成符合 OpenAPI 规范的 JSON 或 YAML 文档。另一方面，YAML 是一种人类可读的数据序列化标准，常用于编写 OpenAPI 规范文件。在代码中通过注释的形式，生成swagger JSON

参考：swagger-editor（所见即所得）

官网传送门

安装依赖

如果是koa项目将swaggeer-ui-express换成koa2-swagger-ui

npm i swaggeer-ui-express swagger-jsdoc -S

配置Swagger

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: '逐风轩Node.js服务端API'
        },
        tags: [
            {
                name: '登录',
                description: '账密登录和授权登录'
            },
            {
                name: '用户管理',
                description: '管理员对用户相关的操作'
            }
            // ... 其他分组
        ]
    },
    apis: [path.join(__dirname, './routes/*.js')]
};

const swaggerSpec = swaggerDoc(options);

let swaggerJson = function (req, res) {
    res.setHeader('Content-Type', 'application/json');
    res.send(swaggerSpec);
}

let swaggerInstall = function (app) {
    if (!app) {
        app = express();
    }

    // 开放相关接口
    app.get('/swagger.json', swaggerJson);

    // 使用 swaggerSpec 生成 swagger 文档页面，并开放在指定路由
    app.use('/swagger', swaggerUI.serve, swaggerUI.setup(swaggerSpec, {
        // 启用 API 探索者模式，允许用户通过界面直接测试 API 操作。
        explorer: true,

        // 启用深度链接功能，用户点击某个 API 操作后，URL 会更新为该操作的唯一标识符，方便分享和书签。
        deepLinking: true,

        // 显示请求持续时间，每次成功发送请求后，Swagger UI 将显示请求所花费的时间。
        displayRequestDuration: true,

        // 设置模型（schemas）展开的默认深度。-1 表示完全折叠，0 表示部分展开，更大的数字表示更多的层次被展开。
        defaultModelsExpandDepth: 2, // 例如，2 表示默认展开两层

        // 控制模型（schemas）的渲染方式。'example' 优先展示示例数据；'model' 优先展示模型结构。
        defaultModelRendering: 'example',

        // 控制 API 操作的默认展开状态。'none' 所有操作都处于折叠状态；'list' 展开操作列表但不显示参数；'full' 完全展开所有操作和参数。
        docExpansion: 'list',

        // 启用筛选框，用户可以在页面顶部的搜索框中输入关键字来快速查找 API 操作。
        filter: true,

        // 指定 API 操作的排序方式。'alpha' 按字母顺序；'method' 按 HTTP 方法；也可以提供一个自定义排序函数。
        operationsSorter: 'alpha',

        // 指定标签的排序方式。'alpha' 按字母顺序；也可以提供一个自定义排序函数。
        tagsSorter: 'alpha',

        // 启用“Try it out”按钮，用户可以通过界面直接测试 API 操作。如果禁用，用户将无法测试。
        tryItOutEnabled: true,

        // 禁用 OpenAPI 规范验证，Swagger UI 不会尝试连接到在线的 Swagger Validator。
        validatorUrl: null,

        // 如果你的 API 使用 OAuth2 认证，需要提供一个重定向 URL，以便在认证流程完成后返回到 Swagger UI。
        oauth2RedirectUrl: '/swagger/oauth2-redirect',

        // 为所有的 API 请求添加拦截器，可以在此处添加认证头信息或其他必要的请求头。
        requestInterceptor: (req) => {
            return req;
        },

        // 为所有的 API 响应添加拦截器，可以在此处处理响应数据或进行错误处理。
        responseInterceptor: (res) => {
            // 对响应进行处理，例如格式化、日志记录等
            return res;
        }
    }));

    return app; // 如果需要链式调用，可以返回 app
}

module.exports = swaggerInstall;

然后在service.js中引用：

const express = require('express');
const swaggerInstall = require('./swagger');

// 创建应用实例
const app = express();
//  配置swagger中间件
if (env != 'production') {
    swaggerInstall(app); // 集成Swagger UI
}

编写API接口注释

使用 @swagger注释风格

示例1：

/**
 * @swagger
 * /login:
 *   post:
 *     tags:
 *       - 登录
 *     summary: 账号登录
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               username:
 *                 type: string
 *                 description: 用户名
 *               password:
 *                 type: string
 *                 description: 密码
 *             required:
 *               - username
 *               - password
 *     responses:
 *        200:
 *          description: Response success
 *          content:
 *           application/json:
 *             example:
 *               code: 200
 *               msg: 操作成功
 *        400:
 *          description: Bad Request
 *        404:
 *          description: API not found
 * */
router.post("/login", async (req, res) => {
    const { username, password } = req.body;
    const result = await userController.login(username, password);
    res.json(result);
});

示例2：

/**
 * @swagger
 * components:
 *   securitySchemes:
 *     authorization:
 *       type: http
 *       scheme: bearer
 *       bearerFormat: JWT
 */
/**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       properties:
 *         id:
 *           type: integer
 *           description: ID.
 *         username:
 *           type: string
 *           description: 用户名
 *         nickName:
 *           type: string
 *           description: 昵称
 *         sex:
 *           type: integer
 *           description: 性别
 *         role:
 *           type: string
 *           description: 角色
 *         avatar:
 *           type: string
 *           description: 头像
 * */

/**
 * @swagger
 * /user/list:
 *   get:
 *     tags:
 *     - 用户管理
 *     summary: 获取用户列表
 *     security:
 *     - authorization: []
 *     responses:
 *       200:
 *         description: Response success
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 code:
 *                   type: integer
 *                   example: 200
 *                 msg:
 *                   type: string
 *                   example: 操作成功
 *                 data:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/User'
 *       400:
 *         description: Bad Request
 *       404:
 *         description: API not found
 */
router.get('/list', async (req, res) => {
    const result = await userController.getUserList();
    res.json(result);
});

生成的效果图参考

Swagger (OpenAPI) 常用注释属性说明

使用 @api 注释风格（JSDoc）

除了 @swagger 注释风格，还可以使用 JSDoc 的 @api 注释风格来定义 API（@api 注释风格不是官方推荐的方式）

补充说明

• @swagger 注释风格 是 OpenAPI 规范的官方推荐方式，提供了更详细的控制和灵活性，适用于复杂的 API 文档
• @api 注释风格 是 JSDoc 中的传统方式，简单易用，适合小型项目或不需要严格遵循 OpenAPI 规范的场景

实际可以根据项目需求和个人偏好来选择最适合的方式定义 API 文档