Debian系统Swagger文档编写指南

以下是在Debian系统上编写Swagger文档的指南：

1. 安装工具

   • 基于Node.js的项目：

     sudo apt update  
     sudo apt install nodejs npm  
     sudo npm install -g swagger-jsdoc swagger-ui-express  
     

   • 基于Python的项目（如Flask）：

     pip install flasgger  
     

2. 创建配置文件

   • 命名为swagger.json或swagger.yaml，定义API元数据：

     {  
       "swagger": "2.0",  
       "info": {  
         "title": "API文档",  
         "version": "1.0.0",  
         "description": "API功能描述"  
       },  
       "basePath": "/api",  
       "paths": {  
         "/users": {  
           "get": {  
             "summary": "获取用户列表",  
             "responses": {  
               "200": {  
                 "description": "成功返回用户列表",  
                 "schema": {  
                   "type": "array",  
                   "items": {  
                     "$ref": "#/definitions/User"  
                   }  
                 }  
               }  
             }  
           }  
         }  
       },  
       "definitions": {  
         "User": {  
           "type": "object",  
           "properties": {  
             "id": { "type": "integer" },  
             "name": { "type": "string" }  
           }  
         }  
       }  
     }  
     

3. 集成到应用

   • Node.js（Express）：

     const express = require('express');  
     const swaggerUi = require('swagger-ui-express');  
     const swaggerDocument = require('./swagger.json');  
     const app = express();  
     app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));  
     app.listen(3000, () => console.log('服务已启动，访问 http://localhost:3000/api-docs') );  
     

   • Python（Flask）：

     from flasgger import Swagger  
     from flask import Flask  
     app = Flask(__name__)  
     Swagger(app, config={  
         'swagger_ui_bundle_js': 'https://rawcdn.githack.com/swagger-api/swagger-ui/v3.23.0/dist/swagger-ui-bundle.js',  
         'openapi': '3.0.0',  
         'info': {  
             'title': 'API文档',  
             'version': '1.0.0'  
         }  
     })  
     

4. 生成与访问文档

   • 直接通过配置文件生成交互式文档，访问路径通常为http://localhost:端口号/api-docs。
   • 如需生成静态文档，可使用swagger-jsdoc命令行工具：

     swagger-jsdoc -i ./swagger.json -o ./docs/output.json  
     

5. 注意事项

   • 遵循OpenAPI规范，使用标准字段（如paths、definitions、responses）。
   • 参数命名需清晰，支持query、path、body等类型。
   • 定期更新文档以匹配代码变更。

参考来源：