Debian系统中Swagger文档生成

在Debian系统中生成Swagger文档，可按以下步骤操作：

1. 安装工具

   • 安装Node.js和npm：sudo apt update && sudo apt install nodejs npm。
   • 安装Swagger工具：
     • 用npm安装swagger-jsdoc（生成文档）：sudo npm install -g swagger-jsdoc。
     • 用npm安装swagger-ui-express（展示文档）：sudo npm install -g swagger-ui-express。
     • 或下载Swagger UI压缩包手动部署。

2. 编写API规范

   • 创建swagger.yaml或swagger.json文件，定义接口路径、参数、模型等。例如：

     openapi: 3.0.0
     info:
       title: Sample API
       version: 1.0.0
     paths:
       /users:
         get:
           summary: List all users
           responses:
             '200':
               description: An array of users
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       $ref: '#/components/schemas/User'
     components:
       schemas:
         User:
           type: object
           properties:
             id: { type: integer, format: int64 }
             name: { type: string }
     ```。  
     
     

3. 生成文档

   • 用swagger-jsdoc生成HTML/Markdown等格式文档：
     swagger-jsdoc -i ./swagger.yaml -o ./docs。
   • 若需生成客户端/服务端代码，可用swagger-codegen（需先安装Java）：
     java -jar swagger-codegen-cli.jar generate -i swagger.yaml -l html2 -o ./output。

4. 集成与访问

   • 用Express托管Swagger UI：创建app.js文件，引入swagger-ui-express并指定文档路径，启动服务后访问http://localhost:3000/api-docs。
   • 可选：通过Nginx反向代理，将Swagger UI绑定到域名或路径。

说明：

• swagger-jsdoc适合从代码注释自动生成文档，swagger-codegen适合从规范文件生成多语言代码或文档。
• 工具安装及配置可参考官方文档，根据项目需求选择合适方式。