Debian系统Swagger文档版本管理技巧

在Debian系统中管理Swagger文档版本，可参考以下技巧：

1. 工具安装
   安装swagger-ui-express等工具，用于生成和展示文档：

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

2. 目录结构设计
   按版本划分API目录，如/api/v1、/api/v2，每个版本独立存放控制器、路由和Swagger配置文件（swagger.json/swagger.yaml）。

3. 版本配置文件
   在每个版本目录中创建Swagger配置文件，明确版本号和API路径。例如：

   // v1/swagger.json  
   {  
     "swagger": "2.0",  
     "info": { "version": "1.0.0" },  
     "paths": { "/users": { "get": { "summary": "获取用户列表（v1）" } } }  
   }  
   

4. 动态路由加载
   在Express应用中通过请求参数（如?version=v2）或路径（如/api-docs/v1）加载对应版本的Swagger文档。示例代码：

   app.use('/api-docs/:version', (req, res) => {  
     const version = req.params.version || 'v1';  
     res.sendFile(path.join(__dirname, `api/${version}/swagger.json`));  
   });  
   

5. 版本控制工具集成
   使用Git管理Swagger文件，通过分支（如feature/v2）隔离不同版本的开发，提交时附清晰日志。

6. 自动化部署
   结合CI/CD工具（如GitHub Actions）自动部署文档，确保版本更新后及时同步至服务器。

7. 文档预览与验证
   通过Swagger Editor在线预览不同版本文档，或使用swagger-codegen生成客户端代码验证兼容性。

关键点：通过目录隔离、动态路由和版本化配置文件实现多版本并存，结合Git确保变更可追溯，适合微服务或长期维护的API项目。