Ubuntu中Swagger文檔怎樣生成與查看

在Ubuntu中生成與查看Swagger文檔的常見方法

Swagger是一套用于描述、構建和文檔化RESTful API的工具集，支持通過代碼注解自動生成文檔，并提供交互式界面測試API。以下是在Ubuntu系統中生成與查看Swagger文檔的具體步驟，涵蓋不同工具和場景：

一、準備工作

在生成Swagger文檔前，需確保Ubuntu系統已安裝Node.js和npm（Node.js包管理器），這是使用Swagger Editor、Swagger UI等工具的基礎：

sudo apt update
sudo apt install -y nodejs npm

二、使用Swagger Editor生成與查看文檔

Swagger Editor是一個開源的在線/離線工具，支持直接編輯Swagger YAML/JSON文件并實時預覽文檔效果。

1. 安裝Swagger Editor

• 方法1：通過npm全局安裝（推薦）
  運行以下命令安裝Swagger Editor CLI：

  sudo npm install -g swagger-editor-cli
  

• 方法2：下載源碼運行
  從GitHub下載Swagger Editor源碼，解壓后進入目錄：

  wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.16.1.tar.gz
  tar -xvf v3.16.1.tar.gz
  cd swagger-editor-3.16.1
  

2. 啟動Swagger Editor

• 通過npm安裝的版本：
  運行以下命令啟動本地服務器（默認端口8080）：

  swagger-editor
  

• 源碼版本：
  先全局安裝http-server，再啟動：

  sudo npm install -g http-server
  http-server -p 8080
  

3. 生成與查看文檔

• 打開瀏覽器訪問http://localhost:8080，進入Swagger Editor界面。
• 導入現有文檔：點擊左側“Import File”，選擇本地的swagger.yaml或swagger.json文件。
• 手動編輯文檔：在編輯器中修改API規范（如端點路徑、參數、響應等），右側會實時顯示文檔預覽。
• 保存文檔：編輯完成后，點擊“File”→“Save”保存為YAML/JSON文件。

三、使用Swagger UI查看生成的文檔

Swagger UI是一個可視化工具，可將Swagger YAML/JSON文件渲染為交互式API文檔，支持在線測試接口。

1. 安裝Swagger UI

• 通過npm安裝：
  運行以下命令全局安裝：

  sudo npm install -g swagger-ui-express
  

2. 配置Swagger UI

創建一個簡單的Node.js服務器，用于托管Swagger文檔：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./path/to/your/swagger.json'); // 替換為你的文檔路徑

const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); // 掛載Swagger UI到/api-docs路徑
const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Swagger UI is running at http://localhost:${PORT}/api-docs`);
});

3. 啟動并查看文檔

• 運行Node.js服務器：

  node your-server-file.js
  

• 打開瀏覽器訪問http://localhost:3000/api-docs，即可看到Swagger UI界面，包含API的所有端點、參數、響應示例等信息。

四、通過編程方式生成Swagger文檔（以Go語言為例）

若項目使用Go語言開發，可使用swag工具根據代碼中的注釋自動生成Swagger文檔。

1. 安裝swag工具

在終端運行以下命令安裝：

go install github.com/swaggo/swag/cmd/swag@latest

2. 添加Swagger注釋

在Go代碼的關鍵位置添加注釋，描述API信息。例如：

package main

import (
	"net/http"
)

// @Summary 獲取用戶信息
// @Description 根據用戶ID返回用戶詳情
// @Tags Users
// @Accept json
// @Produce json
// @Param id path int true "用戶ID"
// @Success 200 {object} User
// @Router /users/{id} [get]
func getUserByID(w http.ResponseWriter, r *http.Request) {
	// 業務邏輯
}

type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

3. 生成文檔

• 在項目根目錄運行以下命令，生成docs目錄（包含swagger.json、swagger.yaml和docs.go）：

  swag init
  

• 生成的文檔可通過Swagger UI查看（參考第三步配置）。

五、集成到構建流程（可選）

若項目使用Maven或Gradle構建，可將Swagger Codegen集成到構建過程中，自動生成文檔。

1. Maven集成

在pom.xml中添加OpenAPI Generator插件：

<build>
  <plugins>
    <plugin>
      <groupId>org.openapitools</groupId>
      <artifactId>openapi-generator-maven-plugin</artifactId>
      <version>5.2.1</version>
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>${project.basedir}/src/main/resources/swagger.yaml</inputSpec>
            <generatorName>html2</generatorName>
            <output>${project.build.directory}/generated-docs</output>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

運行mvn generate-sources即可生成HTML文檔。

2. Gradle集成

在build.gradle中添加OpenAPI Generator任務：

plugins {
  id 'org.openapitools.codegen' version '5.2.1'
}
openApiGenerate {
  inputSpec = file("src/main/resources/swagger.yaml").toString()
  generatorName = 'html2'
  outputDir = file("build/generated-docs")
}

運行gradle openApiGenerate生成文檔。

注意事項

• 確保API服務運行正常，且Swagger文檔路徑（如/v2/api-docs或/swagger.json）可訪問。
• 若遇到CORS問題，需在API服務中配置跨域支持（如Spring Boot中添加@CrossOrigin注解）。
• 根據項目語言和框架選擇合適的工具（如Spring Boot推薦springdoc-openapi，Go推薦swag）。