如何使用Debian Swagger進行版本控制

在Debian系統上使用Swagger進行版本控制的核心流程

1. 準備基礎環境

首先確保Debian系統安裝了必要工具：

sudo apt update
sudo apt install -y git nodejs npm  # 安裝git（版本控制）、Node.js及npm（依賴管理）

2. 初始化項目與安裝Swagger依賴

創建項目目錄并初始化Node.js項目，安裝Swagger UI Express（用于托管文檔）：

mkdir swagger-version-control && cd swagger-version-control
npm init -y  # 初始化npm項目
npm install swagger-ui-express swagger-jsdoc --save  # 安裝Swagger相關依賴

3. 組織API版本目錄結構

通過目錄區分不同版本的API，推薦結構如下：

/swagger-version-control
├── api/
│   ├── v1/                  # 版本1目錄
│   │   ├── controllers/     # 控制器（業務邏輯）
│   │   ├── routes/          # 路由（API端點）
│   │   └── swagger.json     # 版本1的Swagger規范
│   └── v2/                  # 版本2目錄（同理）
│       ├── controllers/
│       ├── routes/
│       └── swagger.json
└── app.js                   # 主應用入口

4. 編寫各版本Swagger規范

在對應版本的swagger.json中明確定義API信息（以v1為例）：

// api/v1/swagger.json
{
  "swagger": "2.0",
  "info": {
    "title": "User API v1",
    "version": "1.0.0",
    "description": "Initial version of User API"
  },
  "basePath": "/api/v1",  // 版本前綴
  "paths": {
    "/users": {
      "get": {
        "summary": "Get all users (v1)",
        "responses": {
          "200": {
            "description": "A list of users",
            "schema": {"type": "array", "items": {"type": "string"}}
          }
        }
      }
    }
  }
}

v2的swagger.json可修改info.version、basePath及paths中的端點（如/users改為/users/details），以體現新功能。

5. 集成Swagger到Express應用

在app.js中動態加載對應版本的Swagger文檔，并配置路由：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const path = require('path');

const app = express();

// 動態獲取版本參數（默認v1）
app.use('/api-docs', (req, res, next) => {
  const version = req.query.version || 'v1';
  const swaggerPath = path.join(__dirname, 'api', version, 'swagger.json');
  
  try {
    const swaggerDocument = require(swaggerPath);
    res.setHeader('Content-Type', 'application/json');
    res.send(swaggerDocument);
  } catch (err) {
    res.status(404).send('Version not found');
  }
});

// 設置Swagger UI（路徑跟隨版本）
app.use('/api-docs/ui', swaggerUi.serve, ({ query }, res, next) => {
  const version = query.version || 'v1';
  res.redirect(`/api-docs?version=${version}`);
});

// 示例路由（對應v1的/users端點）
app.get('/api/v1/users', (req, res) => {
  res.json(['user1', 'user2']);
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
  console.log(`Swagger UI: http://localhost:${PORT}/api-docs/ui?version=v1`);
});

6. 版本控制流程

• 初始化Git倉庫：

  git init
  git add .
  git commit -m "Initial commit with Swagger v1 setup"
  

• 更新API版本：
  當需要升級到v2時，修改api/v2/swagger.json中的info.version、basePath及paths，添加新功能端點（如/users/details）。
• 提交變更：

  git add api/v2/swagger.json routes/v2/ controllers/v2/  # 添加新版本文件
  git commit -m "Add API v2 with updated endpoints"
  git push origin main  # 推送至遠程倉庫
  

7. 訪問不同版本文檔

通過URL參數指定版本，訪問對應Swagger UI：

• v1文檔：http://localhost:3000/api-docs/ui?version=v1
• v2文檔：http://localhost:3000/api-docs/ui?version=v2

8. 可選：自動化部署（GitHub Actions示例）

在項目根目錄創建.github/workflows/deploy.yml，實現代碼推送后自動部署：

name: Deploy Swagger API
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '16'
      - name: Install dependencies
        run: npm install
      - name: Start Swagger UI
        run: node app.js
        env:
          NODE_ENV: production

通過以上步驟，可實現Debian系統上Swagger文檔的版本控制，確保API變更可追溯、文檔同步更新。