Express中使用Swagger

发布时间:2023年12月17日

Swagger


Swagger 是一种规范,用于描述 API 的结构,功能和参数。使用 Swagger 可以提供清晰的可视化 API 文档,可用于 API 交互的文档驱动开发,以及 API 的自动化测试和集成。

  1. 使用 npm 或 yarn 下载。
npm install swagger-jsdoc swagger-ui-express --save
yarn add swagger-jsdoc swagger-ui-express

  1. 在 Express 根目录下的 app.js 中导入。
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

// ...

// definition 字段用于定义 Swagger 规范,apis 字段用于指定使用 Swagger 规范的 API 文件路径
const options = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: 'My API',
            version: '1.0.0'
        }
    },
    apis: ['./routes/*.js']
};

const swaggerSpec = swaggerJsdoc(options);

app.use('/api', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// 其他路由...

  1. 导入后即可在 router 中新增 Swagger 注释。
/**
 * @swagger
 * /users:
 *  get:
 *    summary: 获取所有用户信息
 *    responses:
 *      200:
 *        description: 成功获取所有用户信息
 * 
 *  post:
 *    summary: 创建用户
 *    parameters:
 *      - in: body
 *        name: user
 *        schema:
 *          type: object
 *          properties:
 *            name:
 *              type: string
 *            age:
 *              type: integer
 *    responses:
 *      200:
 *        description: 成功创建用户
 */

如果编写接口时使用的是 ApiFoxPostCat 等支持导出 OpenAI 规范文件的接口工具,
可以导出 OpenAI 规范的接口文件,然后访问 Swagger Editor 并导入接口文件。将左侧显示的内容复制到 Express 的路由文件中,并调整格式如上文所示注释格式即可。

跳转 Express 下的 /api 即可访问所有使用 Swagger 规范的 API 接口。

文章来源:https://blog.csdn.net/Raccon_/article/details/134919924
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。