104 lines
1.9 KiB
Markdown
104 lines
1.9 KiB
Markdown
# 🚀 Quick Start Guide
|
||
|
||
## 安裝
|
||
|
||
### 從原始碼編譯
|
||
```bash
|
||
git clone <your-repo>
|
||
cd go-doc
|
||
make build
|
||
```
|
||
|
||
編譯完成後，執行檔位於 `bin/go-doc`
|
||
|
||
## 基本使用
|
||
|
||
### 1️⃣ 生成 Swagger 2.0（預設）
|
||
```bash
|
||
./bin/go-doc -a example/example.api -d output
|
||
```
|
||
|
||
生成檔案：`output/example.json`
|
||
|
||
### 2️⃣ 生成 OpenAPI 3.0
|
||
```bash
|
||
./bin/go-doc -a example/example.api -d output -s openapi3.0
|
||
```
|
||
|
||
### 3️⃣ 生成 YAML 格式
|
||
```bash
|
||
./bin/go-doc -a example/example.api -d output -y
|
||
```
|
||
|
||
### 4️⃣ 自訂檔名
|
||
```bash
|
||
./bin/go-doc -a example/example.api -d output -f my-api
|
||
```
|
||
|
||
## 常用命令組合
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 編譯
|
||
make build
|
||
|
||
# 生成範例
|
||
make example
|
||
|
||
# 清理
|
||
make clean
|
||
|
||
# 運行測試
|
||
make test
|
||
|
||
# 查看所有命令
|
||
make help
|
||
```
|
||
|
||
## 測試所有格式
|
||
|
||
```bash
|
||
./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`
|