doc-generate/OPENAPI3_GUIDE.md

OpenAPI 3.0 使用指南

📚 概述

從 v1.1.0 開始，go-doc 支援生成 Swagger 2.0 和 OpenAPI 3.0 兩種規格。

🚀 快速開始

生成 Swagger 2.0（預設）

go-doc -a example/example.api -d output

生成 OpenAPI 3.0

go-doc -a example/example.api -d output -s openapi3.0

生成 OpenAPI 3.0 YAML

go-doc -a example/example.api -d output -s openapi3.0 -y

🔍 兩種規格的差異

1. 版本宣告

Swagger 2.0:

{
  "swagger": "2.0"
}

OpenAPI 3.0:

{
  "openapi": "3.0.3"
}

2. 伺服器定義

Swagger 2.0:

{
  "host": "example.com",
  "basePath": "/v1",
  "schemes": ["http", "https"]
}

OpenAPI 3.0:

{
  "servers": [
    {"url": "http://example.com/v1"},
    {"url": "https://example.com/v1"}
  ]
}

3. 資料模型定義

Swagger 2.0:

{
  "definitions": {
    "User": {
      "type": "object",
      "properties": {...}
    }
  }
}

OpenAPI 3.0:

{
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {...}
      }
    }
  }
}

4. 安全定義

Swagger 2.0:

{
  "securityDefinitions": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization"
    }
  }
}

OpenAPI 3.0:

{
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization"
      }
    }
  }
}

5. 請求內容

Swagger 2.0:

{
  "parameters": [
    {
      "in": "body",
      "name": "body",
      "schema": {"$ref": "#/definitions/User"}
    }
  ]
}

OpenAPI 3.0:

{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {"$ref": "#/components/schemas/User"}
      }
    }
  }
}

6. 回應內容

Swagger 2.0:

{
  "responses": {
    "200": {
      "description": "Success",
      "schema": {"$ref": "#/definitions/User"}
    }
  }
}

OpenAPI 3.0:

{
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {"$ref": "#/components/schemas/User"}
        }
      }
    }
  }
}

🎯 使用範例

完整範例：生成多種格式

# Swagger 2.0 JSON
go-doc -a example/example.api -d output -f api-swagger2

# Swagger 2.0 YAML
go-doc -a example/example.api -d output -f api-swagger2 -y

# OpenAPI 3.0 JSON
go-doc -a example/example.api -d output -f api-openapi3 -s openapi3.0

# OpenAPI 3.0 YAML
go-doc -a example/example.api -d output -f api-openapi3 -s openapi3.0 -y

使用 Makefile

# 生成所有範例（包含 Swagger 2.0 和 OpenAPI 3.0）
make example

# 僅編譯
make build

# 測試
make test

⚙️ 轉換邏輯

go-doc 的內部轉換流程：

1. 解析 .api 檔案 → 使用 go-zero 的 API parser
2. 生成 Swagger 2.0 結構 → 基礎的 OpenAPI 2.0 規格
3. 轉換為 OpenAPI 3.0（如果指定）→ 自動轉換：
   • definitions → components/schemas
   • securityDefinitions → components/securitySchemes
   • host/basePath/schemes → servers
   • body parameters → requestBody
4. 序列化輸出 → JSON 或 YAML 格式

🔧 技術細節

使用的函式庫

• Swagger 2.0: github.com/go-openapi/spec
• OpenAPI 3.0: github.com/getkin/kin-openapi

轉換函數

• spec2Swagger(): 將 go-zero API 轉為 Swagger 2.0
• convertSwagger2ToOpenAPI3(): 將 Swagger 2.0 轉為 OpenAPI 3.0

型別轉換

// Swagger 2.0 Type
type: "string"

// OpenAPI 3.0 Type
type: &Types{"string"}

📖 參考資源

• OpenAPI 3.0 Specification
• Swagger 2.0 Specification
• go-zero API 規範

❓ 常見問題

Q: 應該使用哪個版本？

A:

• Swagger 2.0: 如果需要與舊工具或系統相容
• OpenAPI 3.0: 推薦使用，功能更強大且為現代標準

Q: 可以同時生成兩種格式嗎？

A: 可以！執行兩次命令即可：

go-doc -a api.api -d out -f api-v2
go-doc -a api.api -d out -f api-v3 -s openapi3.0

Q: 轉換有什麼限制嗎？

A: 大部分功能都能完整轉換。唯一差異是：

• OpenAPI 3.0 的 server URLs 會根據 schemes 自動生成多個
• 某些 Swagger 2.0 特定的擴展可能不會轉換

Q: 如何驗證生成的文檔？

A: 可以使用以下工具：

• Swagger Editor: https://editor.swagger.io/
• Swagger UI: 本地運行或線上版本
• OpenAPI Generator: 生成客戶端/伺服器代碼來驗證

🎉 總結

go-doc 現在支援：

• ✅ Swagger 2.0 (OpenAPI 2.0)
• ✅ OpenAPI 3.0
• ✅ JSON 和 YAML 輸出
• ✅ 自動轉換
• ✅ 完整的 go-zero API 特性支援

開始使用：

go-doc -a your-api.api -d output -s openapi3.0