在 Swagger 中生成 API 文檔可以通過使用 Swagger UI 或 Swagger Editor 來展示 API 的結構和詳細信息。Swagger 使用 OpenAPI 規範來描述 RESTful API，並且能夠自動生成互動式文檔。

1. 安裝必要的工具

你可以使用以下幾種方法來生成 API 文檔：

a. 使用 Swagger UI

• Swagger UI 是一個靜態文件，可以嵌入到你的應用程序中，通過提供 OpenAPI 規範來生成 API 文檔。
  1. 下載 Swagger UI。
  2. 將 Swagger UI 文件放置到 Web 服務器的靜態資源目錄中。
  3. 打開 index.html，然後在 url 中添加你的 API 的 OpenAPI/Swagger 描述文件 URL。

b. 使用 Swagger Editor

• Swagger Editor 是一個基於 Web 的工具，可以幫助你編寫和生成 OpenAPI 規範文檔。
  1. 打開 Swagger Editor 網頁。
  2. 你可以在編輯器中手動編寫 OpenAPI 規範（YAML 或 JSON 格式）。
  3. 編輯器會根據 OpenAPI 規範自動生成 API 文檔的可視化界面。

c. 使用 Swagger Codegen

• Swagger Codegen 可以根據 OpenAPI 規範來生成 API 的文檔和代碼。
  1. 安裝 Swagger Codegen：

     npm install -g swagger-codegen
     

  2. 使用 Swagger Codegen 生成 API 文檔：

     swagger-codegen generate -i <path_to_your_swagger.yaml> -l html2 -o ./output
     

     這會根據你提供的 OpenAPI 文件生成 HTML 格式的 API 文檔。

2. 編寫 OpenAPI 規範

要生成 API 文檔，首先需要有一個 API 的 OpenAPI 描述文件。這個文件通常用 YAML 或 JSON 格式編寫，描述了 API 的端點（路徑）、HTTP 方法、參數、返回值等。

例如，這是一個簡單的 OpenAPI 規範示例：

openapi: 3.0.0
info:
  title: Simple API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

3. 集成到代碼中自動生成文檔

如果你想在代碼中自動生成 Swagger 文檔，可以根據所使用的框架選擇相應的 Swagger 庫。例如：

a. 在 Node.js 中使用 swagger-jsdoc：

• 安裝 swagger-jsdoc 和 swagger-ui-express：

  npm install swagger-jsdoc swagger-ui-express
  

• 配置 Swagger 文檔：

  const swaggerJsDoc = require('swagger-jsdoc');
  const swaggerUi = require('swagger-ui-express');
  const express = require('express');
  const app = express();
  
  const swaggerOptions = {
    swaggerDefinition: {
      openapi: '3.0.0',
      info: {
        title: 'Simple API',
        version: '1.0.0',
      },
    },
    apis: ['./routes/*.js'], // 路由的文件位置
  };
  
  const swaggerDocs = swaggerJsDoc(swaggerOptions);
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
  
  app.listen(3000, () => console.log('Server running on port 3000'));
  

b. 在 Spring Boot 中使用 springdoc-openapi：

• 在 pom.xml 中加入依賴：

  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.9</version>
  </dependency>
  

• 啟動 Spring Boot 服務後，可以通過 http://localhost:8080/swagger-ui.html 來查看 API 文檔。

4. 使用 Swagger UI 顯示文檔

在服務器端正確設置了 OpenAPI 描述文件後，Swagger UI 就可以通過讀取該文件生成可視化的 API 文檔。你可以通過設置 Swagger UI 頁面來展示文檔。

總結

生成 API 文檔的基本步驟是：

1. 編寫 OpenAPI 規範。
2. 使用 Swagger UI 或 Swagger Editor 將規範可視化為 API 文檔。
3. 集成 Swagger 到應用中，自動生成並展示 API 文檔。