Debian系統中Swagger如何進行版本控制

在Debian系統上對Swagger API進行版本控制，可以遵循以下步驟：

安裝必要的軟件包

首先，確保你的Debian系統已經安裝了必要的軟件包，包括 git 和 nodejs（如果你打算使用 Swagger UI）。

sudo apt update
sudo apt install git nodejs npm

創建一個新的Git倉庫

在你的項目目錄中，初始化一個新的Git倉庫：

cd /path/to/your/swagger/project
git init

添加Swagger文件

將你的Swagger API定義文件（通常是 swagger.yaml 或 swagger.json）添加到項目目錄中：

git add swagger.yaml

提交更改

將更改提交到Git倉庫：

git commit -m "Initial commit of Swagger API"

創建分支

為了更好地管理不同版本的API，你可以為每個版本創建一個單獨的分支。例如，如果你想創建一個名為 v1 的版本分支，可以運行以下命令：

git checkout -b v1

對API進行更改

在對API進行更改時，請確保在正確的分支上進行操作。例如，如果你正在對版本1進行更改，請確保你在 v1 分支上。完成更改后，使用以下命令將更改添加到Git倉庫并提交：

git add swagger.yaml
git commit -m "Update API for version 1"

合并分支

當你想要將一個版本的更改合并到主分支時（例如，將版本1的更改合并到主分支），首先切換到主分支，然后使用以下命令合并：

git checkout master
git merge v1

推送更改

將你的更改推送到遠程倉庫（例如，GitHub或GitLab）：

git push origin master

配置Express應用以支持多版本

為了在Express應用中支持多版本的Swagger文檔，你可以按照以下步驟操作：

1. 創建API版本控制目錄結構：

   /api
     /v1
       /controllers
         userController.js
       /routes
         userRoutes.js
     /v2
       /controllers
         userControllerV2.js
       /routes
         userRoutesV2.js
   

2. 配置Swagger：在每個版本的API目錄中創建一個Swagger配置文件（例如 swagger.json），并定義該版本的API規范。

   v1/swagger.json：

   {
     "swagger": "2.0",
     "info": {
       "title": "User API",
       "version": "1.0.0"
     },
     "paths": {
       "/users": {
         "get": {
           "summary": "Get all users",
           "responses": {
             "200": {
               "description": "A list of users"
             }
           }
         }
       }
     }
   }
   

   v2/swagger.json：

   {
     "swagger": "2.0",
     "info": {
       "title": "User API",
       "version": "2.0.0"
     },
     "paths": {
       "/users": {
         "get": {
           "summary": "Get all users with additional details",
           "responses": {
             "200": {
               "description": "A list of users with additional details"
             }
           }
         }
       }
     }
   }
   

3. 配置Express應用：在你的Express應用中，根據請求的版本號來加載相應的Swagger配置和路由。

   const express = require('express');
   const swaggerUi = require('swagger-ui-express');
   const swaggerDocumentV1 = require('./api/v1/swagger.json');
   const swaggerDocumentV2 = require('./api/v2/swagger.json');
   const app = express();
   const port = 3000;
   
   // Middleware to determine API version
   app.use('/api-docs', (req, res, next) => {
     const version = req.query.version || 'v1'; // Default to v1 if no version is specified
     switch (version) {
       case 'v2':
         res.setHeader('Content-Type', 'application/json');
         res.send(swaggerDocumentV2);
         break;
       default:
         res.send(swaggerDocumentV1);
         break;
     }
   });
   
   // Serve Swagger UI for v1
   app.use('/api-docs/v1', swaggerUi.serve, swaggerUi.setup(swaggerDocumentV1));
   // Serve Swagger UI for v2
   app.use('/api-docs/v2', swaggerUi.serve, swaggerUi.setup(swaggerDocumentV2));
   
   // Start the server
   app.listen(port, () => {
     console.log(`Server is running on http://localhost:${port}`);
   });
   

4. 測試API版本管理：現在，你可以通過訪問不同的URL來測試不同版本的API文檔：

   • 默認顯示v1版本的API文檔：http://localhost:3000/api-docs
   • 顯示v2版本的API文檔：http://localhost:3000/api-docs?version=v2

通過以上步驟，你可以在Debian系統上實現Swagger API版本管理，并且可以輕松地添加新的API版本。