doc-generate/QUICK_START.md

🚀 Quick Start Guide

安裝

從原始碼編譯

git clone <your-repo>
cd go-doc
make build

編譯完成後，執行檔位於 bin/go-doc

基本使用

1️⃣ 生成 Swagger 2.0（預設）

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

生成檔案：output/example.json

2️⃣ 生成 OpenAPI 3.0

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

3️⃣ 生成 YAML 格式

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

4️⃣ 自訂檔名

./bin/go-doc -a example/example.api -d output -f my-api

常用命令組合

# Swagger 2.0 JSON
./bin/go-doc -a api.api -d docs

# Swagger 2.0 YAML
./bin/go-doc -a api.api -d docs -y

# OpenAPI 3.0 JSON
./bin/go-doc -a api.api -d docs -s openapi3.0

# OpenAPI 3.0 YAML
./bin/go-doc -a api.api -d docs -s openapi3.0 -y

完整參數

-a, --api string            API 檔案路徑（必要）
-d, --dir string            輸出目錄（必要）
-f, --filename string       輸出檔名（不含副檔名）
-s, --spec-version string   規格版本：swagger2.0 或 openapi3.0（預設：swagger2.0）
-y, --yaml                  生成 YAML 格式（預設：JSON）
-h, --help                  顯示說明
-v, --version               顯示版本

使用 Makefile

# 編譯
make build

# 生成範例
make example

# 清理
make clean

# 運行測試
make test

# 查看所有命令
make help

測試所有格式

./test_all_formats.sh

查看範例

生成的範例檔案位於：

• example/test_output/example_swagger2.json - Swagger 2.0 JSON
• example/test_output/example_swagger2.yaml - Swagger 2.0 YAML
• example/test_output/example_openapi3.json - OpenAPI 3.0 JSON
• example/test_output/example_openapi3.yaml - OpenAPI 3.0 YAML

更多資訊

• 完整文檔：README.md
• OpenAPI 3.0 指南：OPENAPI3_GUIDE.md
• 版本變更：CHANGELOG.md