Node server生成Swagger接口文档

本文介绍使用NodeJs搭建的后端server快速生成Swagger接口文档的技巧。将Node.js服务器的路由信息转换成Swagger(现称OpenAPI Specification)格式的步骤通常如下:

  1. 安装必要的Node.js库 :首先,需要在Node.js项目中安装Swagger相关的库。一个常用的库是swagger-jsdoc,它可以根据JSDoc注释自动创建Swagger文档。同时,swagger-ui-express可以用来在你的Express应用中提供一个可视化的Swagger UI。

    bash 复制代码
    npm install swagger-jsdoc swagger-ui-express --save
  2. 添加JSDoc注释 :在路由处理器中使用JSDoc注释来描述API。swagger-jsdoc将使用这些注释生成Swagger文档。

    例如:

    javascript 复制代码
    /**
     * @swagger
     * /users:
     *   get:
     *     description: 返回用户列表
     *     responses:
     *       200:
     *         description: 成功获取用户列表
     */
    app.get('/users', (req, res) => {
      // ...
    });
  3. 配置swagger-jsdoc :在应用程序中配置swagger-jsdoc,以便能够收集所有的JSDoc注释并生成Swagger文档。

    javascript 复制代码
    const swaggerJSDoc = require('swagger-jsdoc');
    const swaggerDefinition = {
      openapi: '3.0.0',
      info: {
        title: 'Express API with Swagger',
        version: '1.0.0',
      },
      servers: [
        {
          url: 'http://localhost:3000',
          description: 'Development server',
        },
      ],
    };
    
    const options = {
      swaggerDefinition,
      // 路径到API文档的地方
      apis: ['./routes/*.js'], // e.g. assuming your routes are in a directory called "routes"
    };
    
    const swaggerSpec = swaggerJSDoc(options);
  4. 使用swagger-ui-express为Swagger文档提供UI

    javascript 复制代码
    const swaggerUi = require('swagger-ui-express');
    
    // 在你的应用中设置路由服务Swagger文档
    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
  5. 运行你的应用并访问Swagger UI :当运行Node.js应用时,可以访问http://localhost:3000/api-docs(或配置的其他地址)来查看和测试API。


English version

The steps to transform the routing information of a Node.js server into Swagger (now known as OpenAPI Specification) format are typically as follows:

  1. Install Necessary Node.js Libraries : First, necessary Swagger-related libraries need to be installed in the Node.js project. A commonly used library is swagger-jsdoc, which can automatically create Swagger documentation based on JSDoc comments. Additionally, swagger-ui-express can be used to provide a visual Swagger UI in an Express application.

    bash 复制代码
    npm install swagger-jsdoc swagger-ui-express --save
  2. Add JSDoc Comments : Use JSDoc comments to describe the API in the route handlers. swagger-jsdoc will use these comments to generate Swagger documentation.

    For example:

    javascript 复制代码
    /**
     * @swagger
     * /users:
     *   get:
     *     description: Returns a list of users
     *     responses:
     *       200:
     *         description: Successfully retrieved list of users
     */
    app.get('/users', (req, res) => {
      // ...
    });
  3. Configure swagger-jsdoc : Configure swagger-jsdoc in the application to collect all JSDoc comments and generate Swagger documentation.

    javascript 复制代码
    const swaggerJSDoc = require('swagger-jsdoc');
    const swaggerDefinition = {
      openapi: '3.0.0',
      info: {
        title: 'Express API with Swagger',
        version: '1.0.0',
      },
      servers: [
        {
          url: 'http://localhost:3000',
          description: 'Development server',
        },
      ],
    };
    
    const options = {
      swaggerDefinition,
      // Path to the API docs
      apis: ['./routes/*.js'], // e.g. assuming your routes are in a directory called "routes"
    };
    
    const swaggerSpec = swaggerJSDoc(options);
  4. Use swagger-ui-express to Provide UI for Swagger Documentation:

    javascript 复制代码
    const swaggerUi = require('swagger-ui-express');
    
    // Set up a route in your application to serve the Swagger documentation
    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
  5. Run Your Application and Access Swagger UI : Now, when running the Node.js application, the Swagger UI can be accessed at http://localhost:3000/api-docs (or another configured address) to view and test the API.

Remember to replace the paths and information in the example with those in the actual application. The above steps require some manual work in the code, but once completed, a real-time updated API documentation is obtained, which is very convenient for API testing and collaborative work.

相关推荐
风若飞4 小时前
npm ERR! code CERT_HAS_EXPIRED
前端·npm·node.js
csdn_aspnet4 小时前
Windows、Linux 系统 nodejs 和 npm 版本更新及错误修复
linux·windows·npm·node.js
北城笑笑4 小时前
NodeJS 8 ,从 0 到 1:npm 包发布与更新全流程指南( 含多场景适配与踩坑总结 )
前端·npm·node.js·github
码码哈哈0.04 小时前
npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1,因为在此系统上禁止运行脚
前端·npm·node.js
歪歪1006 小时前
webpack 配置文件中 mode 有哪些模式?
开发语言·前端·javascript·webpack·前端框架·node.js
歪歪1006 小时前
如何配置Webpack以实现按需加载模块?
开发语言·前端·webpack·node.js
No喜欢吃香菜.16 小时前
node.js卸载并重新安装(超详细图文步骤)
node.js
qq_124987075316 小时前
基于node.js+vue的医院陪诊系统的设计与实现(源码+论文+部署+安装)
前端·vue.js·node.js·毕业设计
草梅友仁17 小时前
草梅 Auth 1.7.0 发布 Demo 模式 | 2025 年第 37 周草梅周报
开源·node.js·github
谢尔登18 小时前
【Webpack】模块联邦
前端·webpack·node.js