如何使用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变更可追溯、文档同步更新。

0 赞

0 踩