Debian系统中Swagger API版本控制

在Debian系统中实现Swagger API版本控制可以通过以下几个步骤来完成：

安装Swagger工具

首先，确保你的Debian系统上已经安装了Swagger工具。你可以使用以下命令来安装Swagger：

sudo apt update
sudo apt install swagger-ui-express

创建API规范文件

使用OpenAPI Specification (OAS) 定义你的API。你可以手动编写YAML或JSON格式的规范文件，或者使用Swagger Editor在线工具来创建和编辑规范。

例如，创建两个不同版本的API规范文件：

example-v1.yaml:

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /items:
    get:
      summary: List all items (v1)
      responses:
        '200':
          description: An array of items

example-v2.yaml:

openapi: 3.0.0
info:
  title: Sample API
  version: 2.0.0
paths:
  /items:
    get:
      summary: List all items with additional details (v2)
      responses:
        '200':
          description: An array of items with additional details

集成Swagger UI

在你的Express应用程序中集成Swagger UI，并指向你的API规范文件。

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

const app = express();

const swaggerDocumentV1 = YAML.load('./api/v1/example-v1.yaml');
const swaggerDocumentV2 = YAML.load('./api/v2/example-v2.yaml');

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.setHeader('Content-Type', 'application/json');
      res.send(swaggerDocumentV1);
      break;
  }
});

app.use('/api-docs/v1', swaggerUi.serve, swaggerUi.setup(swaggerDocumentV1));
app.use('/api-docs/v2', swaggerUi.serve, swaggerUi.setup(swaggerDocumentV2));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

版本管理

为了实现API文档的版本管理，你可以在规范文件中为每个版本创建不同的路径或标签。然后，你可以根据请求的URL路径或HTTP头中的自定义标签来提供不同版本的API文档。

部署和测试

部署你的应用程序，并通过浏览器访问不同的版本路径来测试API文档是否正确显示。

http://localhost:3000/api-docs  # 默认显示v1版本的API文档
http://localhost:3000/api-docs?version=v2  # 显示v2版本的API文档

通过这种方式，你可以在Debian系统上实现Swagger API版本管理，并且可以轻松地添加新的API版本。