如何在Ubuntu上自定義Swagger

在Ubuntu上自定義Swagger（現在通常指的是OpenAPI規范）可以通過幾個步驟來完成。以下是一個基本的指南，幫助你開始自定義Swagger文檔：

1. 安裝Swagger工具: 首先，你需要安裝Swagger工具，比如Swagger Editor或者Swagger UI。Swagger Editor是一個在線工具，可以用來編輯和預覽Swagger規范。如果你想在本地環境中工作，你可以安裝Swagger UI。

   使用npm（Node.js的包管理器）來安裝Swagger UI：

   sudo apt update
   sudo apt install nodejs npm
   sudo npm install -g swagger-ui-express
   

2. 創建Swagger規范: 你可以手動編寫Swagger JSON或YAML文件，或者使用Swagger Editor來創建。如果你使用Swagger Editor，只需訪問Swagger Editor Online，它會提供一個基本的Swagger模板，你可以在此基礎上進行編輯。

3. 自定義Swagger規范: 根據你的API需求，編輯Swagger規范文件。你需要定義路徑（paths）、操作（operations）、參數（parameters）、模型（models）等。例如：

   swagger: '2.0'
   info:
     title: Sample API
     description: A sample API to illustrate Swagger customization
     version: 1.0.0
   paths:
     /users:
       get:
         summary: List all users
         responses:
           '200':
             description: An array of users
             schema:
               type: array
               items:
                 $ref: '#/definitions/User'
   definitions:
     User:
       type: object
       properties:
         id:
           type: integer
           format: int64
         name:
           type: string
       required:
         - id
         - name
   

4. 集成Swagger UI: 如果你已經安裝了swagger-ui-express，你可以創建一個簡單的Node.js應用程序來托管Swagger UI，并將其與你自定義的Swagger規范文件關聯起來。

   創建一個新的Node.js文件，比如app.js，并添加以下代碼：

   const express = require('express');
   const swaggerUi = require('swagger-ui-express');
   const YAML = require('yamljs');
   
   const app = express();
   const swaggerDocument = YAML.load('./path/to/your/swagger.json'); // 替換為你的Swagger規范文件路徑
   
   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
   
   const port = process.env.PORT || 3000;
   app.listen(port, () => {
     console.log(`Server is running at http://localhost:${port}/api-docs`);
   });
   

   確保你已經安裝了所有必要的Node.js模塊：

   npm install express swagger-ui-express yamljs
   

5. 運行你的應用程序: 在終端中運行你的Node.js應用程序：

   node app.js
   

   現在，你可以在瀏覽器中訪問http://localhost:3000/api-docs來查看和測試你的自定義Swagger文檔。

請注意，這些步驟提供了一個基本的指南，Swagger的自定義可以非常深入，包括添加安全方案、響應模型、請求體參數等。你可能需要根據你的具體需求來調整和擴展你的Swagger規范。