如何利用Swagger提升Debian應用

要利用Swagger提升Debian應用，可以按照以下步驟進行：

1. 安裝Swagger工具

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

sudo apt update
sudo apt install swagger-ui-express

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

為了管理不同版本的API，你可以創建一個目錄結構來組織你的API文件。例如：

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

3. 配置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"
          }
        }
      }
    }
  }
}

4. 配置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.setHeader('Content-Type', 'application/json');
      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}`);
});

5. 測試API版本管理

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

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

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

6. 使用Swagger注解

在你的控制器類中使用Swagger注解來描述API接口：

import { Api, ApiOperation, ApiParam } from 'swagger';
import { Request, Response } from 'express';

@Api(tags = "Sample API")
@RestController
@RequestMapping("/api")
export class SampleController {
  @GetMapping("/hello")
  @ApiOperation({ value: "Say hello", response: { type: String } })
  sayHello(): Response {
    return { message: "Hello, World!" };
  }

  @PostMapping("/data")
  @ApiOperation({ value: "Send data", requestBody: { required: true, content: { schema: { type: String } } }, response: { type: String } })
  sendData(@ApiParam({ name: "data", description: "The data to send", required: true }) @RequestBody data: string): Response {
    return { received: data };
  }
}

7. 訪問API文檔

在Swagger UI中，你可以看到所有通過注解描述的API接口，可以在線嘗試調用這些接口，查看請求和響應示例。

通過以上步驟，你可以在Debian系統上成功配置和使用Swagger來生成和管理API文檔，從而提升你的應用的開發效率和可維護性。