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項目。