如何自定義Ubuntu上的Swagger

在Ubuntu上自定義Swagger（現在通常指的是OpenAPI規范，以前稱為Swagger）通常涉及幾個步驟，包括安裝Swagger工具、配置Swagger文檔以及可能的代碼生成。以下是一個基本的指南，幫助你在Ubuntu系統上自定義Swagger：

1. 安裝Swagger工具: 你可以使用npm（Node.js的包管理器）來安裝Swagger命令行工具。首先，確保你已經安裝了Node.js和npm。如果沒有安裝，可以通過以下命令安裝：

   sudo apt update
   sudo apt install nodejs npm
   

   然后，安裝Swagger CLI：

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

2. 創建Swagger配置文件: 創建一個YAML或JSON格式的Swagger配置文件，用于定義你的API規范。例如，創建一個名為swagger.json的文件，并添加你的API信息：

   {
     "swagger": "2.0",
     "info": {
       "description": "My API",
       "version": "1.0.0"
     },
     "basePath": "/api",
     "paths": {
       "/users": {
         "get": {
           "summary": "List all users",
           "responses": {
             "200": {
               "description": "An array of users"
             }
           }
         }
       }
     }
   }
   

3. 集成Swagger到你的應用: 如果你使用的是Express框架，可以使用swagger-ui-express中間件來集成Swagger UI到你的應用中。首先，安裝Express和swagger-ui-express：

   sudo npm install express swagger-ui-express
   

   然后，在你的Express應用中使用swagger-ui-express：

   const express = require('express');
   const swaggerUi = require('swagger-ui-express');
   const swaggerDocument = require('./swagger.json');
   
   const app = express();
   
   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
   
   const port = process.env.PORT || 3000;
   app.listen(port, () => {
     console.log(`Server is running on port ${port}`);
   });
   

4. 自定義Swagger UI: Swagger UI提供了多種方式來自定義外觀和行為。你可以通過傳遞選項給swaggerUi.setup()函數來自定義UI。例如，你可以更改UI的主題、布局和深度：

   const ui = swaggerUi.serve({
     swaggerDocument: swaggerDocument,
     deepLinking: true,
     presets: [
       swaggerUi.presets.apis,
       swaggerUi.presets.promises
     ],
     plugins: [
       swaggerUi.plugins.DownloadUrl
     ],
     layout: "StandaloneLayout"
   }, (req, res) => {
     res.setHeader('Content-Type', 'text/html');
     res.write(ui);
     res.end();
   });
   app.use('/api-docs', ui);
   

5. 運行你的應用: 運行你的Node.js應用，然后訪問http://localhost:3000/api-docs來查看Swagger UI界面。

請注意，這些步驟提供了一個基本的指南，具體的自定義選項和方法可能會隨著Swagger工具的更新而變化。建議查看最新的Swagger文檔和資源以獲取最新信息。