Swagger如何在Linux環境下實現版本控制

在Linux環境下，使用Swagger實現API版本控制可以通過以下步驟進行：

1. 安裝Swagger工具：

   • 首先，確保你的Linux系統上已經安裝了Swagger。你可以使用npm（Node.js的包管理器）來安裝Swagger CLI工具。

   npm install -g swagger-jsdoc swagger-ui-express
   

2. 創建Swagger配置文件：

   • 在你的項目中創建一個Swagger配置文件，通常命名為swagger.js或swagger.json。這個文件將定義你的API規范。

   const swaggerJsDoc = require('swagger-jsdoc');
   
   const swaggerOptions = {
     swaggerDefinition: {
       openapi: '3.0.0',
       info: {
         title: 'My API',
         version: '1.0.0',
         description: 'API documentation for My API',
       },
     },
     apis: ['./routes/*.js'], // 指定包含API路由的文件
   };
   
   const swaggerDocs = swaggerJsDoc(swaggerOptions);
   module.exports = swaggerDocs;
   

3. 集成Swagger UI：

   • 在你的Express應用中集成Swagger UI，以便可以通過瀏覽器查看和測試API文檔。

   const express = require('express');
   const swaggerUi = require('swagger-ui-express');
   const swaggerDocs = require('./swagger');
   
   const app = express();
   
   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
   
   // 其他路由和中間件
   
   const PORT = process.env.PORT || 3000;
   app.listen(PORT, () => {
     console.log(`Server is running on port ${PORT}`);
   });
   

4. 版本控制：

   • 為了實現API版本控制，你可以在Swagger配置文件中為每個版本定義不同的路徑或標簽。
   • 例如，你可以創建兩個不同的Swagger配置文件，一個用于版本1.0，另一個用于版本2.0。

   // swagger-v1.js
   const swaggerJsDoc = require('swagger-jsdoc');
   
   const swaggerOptionsV1 = {
     swaggerDefinition: {
       openapi: '3.0.0',
       info: {
         title: 'My API',
         version: '1.0.0',
         description: 'API documentation for My API version 1.0',
       },
     },
     apis: ['./routes/v1/*.js'],
   };
   
   const swaggerDocsV1 = swaggerJsDoc(swaggerOptionsV1);
   module.exports = swaggerDocsV1;
   
   // swagger-v2.js
   const swaggerJsDoc = require('swagger-jsdoc');
   
   const swaggerOptionsV2 = {
     swaggerDefinition: {
       openapi: '3.0.0',
       info: {
         title: 'My API',
         version: '2.0.0',
         description: 'API documentation for My API version 2.0',
       },
     },
     apis: ['./routes/v2/*.js'],
   };
   
   const swaggerDocsV2 = swaggerJsDoc(swaggerOptionsV2);
   module.exports = swaggerDocsV2;
   

   • 然后在Express應用中分別集成這兩個版本的Swagger UI。

   const express = require('express');
   const swaggerUi = require('swagger-ui-express');
   const swaggerDocsV1 = require('./swagger-v1');
   const swaggerDocsV2 = require('./swagger-v2');
   
   const app = express();
   
   app.use('/api-docs/v1', swaggerUi.serve, swaggerUi.setup(swaggerDocsV1));
   app.use('/api-docs/v2', swaggerUi.serve, swaggerUi.setup(swaggerDocsV2));
   
   // 其他路由和中間件
   
   const PORT = process.env.PORT || 3000;
   app.listen(PORT, () => {
     console.log(`Server is running on port ${PORT}`);
   });
   

通過這種方式，你可以在Linux環境下使用Swagger實現API版本控制，并且可以通過不同的路徑訪問不同版本的API文檔。