doc-generate/OPENAPI3_GUIDE.md

# OpenAPI 3.0 使用指南

## 📚 概述

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

## 🚀 快速開始

### 生成 Swagger 2.0（預設）
```bash
go-doc -a example/example.api -d output
```

### 生成 OpenAPI 3.0
```bash
go-doc -a example/example.api -d output -s openapi3.0
```

### 生成 OpenAPI 3.0 YAML
```bash
go-doc -a example/example.api -d output -s openapi3.0 -y
```

## 🔍 兩種規格的差異

### 1. 版本宣告
**Swagger 2.0:**
```json
{
  "swagger": "2.0"
}
```

**OpenAPI 3.0:**
```json
{
  "openapi": "3.0.3"
}
```

### 2. 伺服器定義
**Swagger 2.0:**
```json
{
  "host": "example.com",
  "basePath": "/v1",
  "schemes": ["http", "https"]
}
```

**OpenAPI 3.0:**
```json
{
  "servers": [
    {"url": "http://example.com/v1"},
    {"url": "https://example.com/v1"}
  ]
}
```

### 3. 資料模型定義
**Swagger 2.0:**
```json
{
  "definitions": {
    "User": {
      "type": "object",
      "properties": {...}
    }
  }
}
```

**OpenAPI 3.0:**
```json
{
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {...}
      }
    }
  }
}
```

### 4. 安全定義
**Swagger 2.0:**
```json
{
  "securityDefinitions": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization"
    }
  }
}
```

**OpenAPI 3.0:**
```json
{
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization"
      }
    }
  }
}
```

### 5. 請求內容
**Swagger 2.0:**
```json
{
  "parameters": [
    {
      "in": "body",
      "name": "body",
      "schema": {"$ref": "#/definitions/User"}
    }
  ]
}
```

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

### 6. 回應內容
**Swagger 2.0:**
```json
{
  "responses": {
    "200": {
      "description": "Success",
      "schema": {"$ref": "#/definitions/User"}
    }
  }
}
```

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

## 🎯 使用範例

### 完整範例：生成多種格式

```bash
# 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

```bash
# 生成所有範例（包含 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

### 型別轉換
```go
// Swagger 2.0 Type
type: "string"

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

## 📖 參考資源

- [OpenAPI 3.0 Specification](https://spec.openapis.org/oas/v3.0.3)
- [Swagger 2.0 Specification](https://swagger.io/specification/v2/)
- [go-zero API 規範](https://go-zero.dev/docs/tutorials)

## ❓ 常見問題

### Q: 應該使用哪個版本？
**A:** 
- **Swagger 2.0**: 如果需要與舊工具或系統相容
- **OpenAPI 3.0**: 推薦使用，功能更強大且為現代標準

### Q: 可以同時生成兩種格式嗎？
**A:** 可以！執行兩次命令即可：
```bash
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 特性支援

開始使用：
```bash
go-doc -a your-api.api -d output -s openapi3.0
```