如何利用Debian Swagger進行API版本管理

在Debian系統中使用Swagger（OpenAPI Specification）進行API版本管理，可以通過以下幾個步驟來完成：

1. 安裝Swagger工具

首先，確保你的Debian系統上已經安裝了Swagger工具。你可以使用以下命令來安裝Swagger：

sudo apt update
sudo apt install swagger-ui-express

2. 創建API規范文件

使用OpenAPI Specification（OAS）定義你的API。你可以手動編寫YAML或JSON格式的規范文件，或者使用Swagger Editor在線工具來創建和編輯規范。

example-v1.yaml:

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /items:
    get:
      summary: List all items
      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
      responses:
        '200':
          description: An array of items with more details

3. 集成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 = require('./api/v1/swagger.json');
const swaggerDocumentV2 = require('./api/v2/swagger.json');

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}`);
});

4. 版本管理

為了實現API文檔的版本管理，你可以在規范文件中為每個版本創建不同的路徑或標簽。然后，你可以根據請求的URL路徑或HTTP頭中的自定義標簽來提供不同版本的API文檔。

5. 部署和測試

部署你的應用程序，并通過瀏覽器訪問不同的版本路徑來測試API文檔是否正確顯示。

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

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