開發指南

設定

# 複製儲存庫並安裝開發依賴項
git clone https://github.com/f5-sales-demo/api-specs.git
cd api-specs
make dev-install

# 安裝 Spectral CLI（lint 階段所需）
npm install -g @stoplight/spectral-cli

make dev-install 會在 .venv/ 中建立虛擬環境，並安裝包含開發附加套件（pytest、ruff、mypy）的專案。

環境變數

即時 API 驗證需要：

export F5XC_API_URL="https://example-tenant.console.ves.volterra.io"
export F5XC_API_TOKEN="your-api-token"

若未設定這些變數，make validate 將回退至乾跑模式。

執行管線

完整管線

make all
# 執行：download → validate → spectral-lint → reconcile → spectral-gate → release

個別階段

make download        # 取得上游規格
make validate        # 執行即時 API 測試（需要 API 令牌）
make validate-dry    # 乾跑模式（不進行 API 呼叫）
make spectral-lint   # 對原始規格執行 Spectral 探索模式
make reconcile       # 根據兩份報告套用修正
make spectral-gate   # 對調和後的規格執行 Spectral 品質關卡
make release         # 建置發佈套件

文件

make docs-generate   # 從報告重新產生 docs/01-validation-report.mdx
make docs            # 建置完整文件網站
make docs-serve      # 具有熱重載功能的本機開發伺服器

執行測試

make test           # 含覆蓋率的 pytest
make lint           # ruff 檢查 + 格式檢查
make typecheck      # mypy 型別檢查
make ci-test        # 以上三者全部執行（用於 CI）

若已安裝，pre-commit hooks 會在提交時自動執行：

make pre-commit-install   # 安裝 git hooks
make pre-commit           # 手動執行所有 hooks

專案結構

scripts/
  download.py           # 階段 1：從 F5 取得規格
  validate.py           # 階段 2：即時 API 測試
  spectral_lint.py      # 階段 3/5：Spectral linting 適配器
  reconcile.py          # 階段 4：對規格套用修正
  release.py            # 階段 6：打包發佈
  generate_docs.py      # 從報告產生 MDX
  utils/
    auth.py             # F5 XC API 認證
    constraint_validator.py  # 約束測試 + 差異類型
    report_generator.py      # 報告格式化
    schemathesis_runner.py   # Schemathesis 測試編排
    spec_loader.py           # 規格 I/O + JSON 格式化

config/
  validation.yaml       # 管線配置
  endpoints.yaml        # 即時測試的基準端點

spectral/
  functions/
    f5-path-params.js   # 自訂 Spectral 函式

docs/                   # Starlight MDX 文件
tests/                  # pytest 測試套件
release/specs/          # 輸出：調和後的規格檔案
reports/                # 輸出：驗證及 Spectral 報告

新增修正方法

要為調和器新增 Spectral 自動修正：

新增規則至 .spectral.yaml，設定所需的嚴重性等級。
啟用自動修正，在 config/validation.yaml 的 spectral.auto_fix 下：
```
spectral:
  auto_fix:
    your-new-rule: true
```

新增修正方法至 scripts/reconcile.py 中的 SpecReconciler：

def _fix_your_rule(self, spec: dict, discrepancy: Discrepancy) -> dict | None:
    """Fix description."""
    # Modify spec in place
    # Return spec if changed, None if no change needed
    return spec

註冊至 _apply_spectral_fix 分發器：

spectral_fixers = {
    # ... existing fixers ...
    "spectral:your-new-rule": self._fix_your_rule,
}

新增測試以涵蓋新的修正方法。

新增 Spectral 規則

要新增帶有 JavaScript 函式的自訂 Spectral 規則：

在 spectral/functions/your-rule.js 中建立函式。匯出一個接收 (targetVal, options, context) 的預設函式，並回傳 {message, path} 物件陣列。

在 spectral-pipeline.yaml 中註冊：

functions:
  - f5-path-params
  - your-rule

rules:
  your-rule:
    description: "What it checks"
    message: "{{error}}"
    severity: error
    given: "$.paths[*]"
    then:
      function: your-rule

CI 管線

GitHub Actions 工作流程（validate-and-release.yml）在以下情況執行：

排程：每日 UTC 時間上午 6 點
推送至 main：當 scripts/、config/ 或 pyproject.toml 有變更時
手動觸發：可選擇強制發佈或乾跑模式

工作流程包含四個工作：

validate —— 下載規格、執行驗證、Spectral lint、調和、Spectral 品質關卡
check-release-needed —— 比較內容雜湊值以判斷是否需要發佈
release —— 打包並建立 GitHub Release（僅在內容有變更時）
update-docs —— 重新產生 01-validation-report.mdx，若有變更則開啟 PR

若任何工作失敗，notify 工作會建立 GitHub issue。

分支與 PR 工作流程

所有變更遵循：Issue -> 分支 -> PR -> CI 通過 -> 合併。

分支命名：feature/<issue>-desc、fix/<issue>-desc、docs/<issue>-desc
PR 必須連結 issue（在描述中使用 Closes #N）
必要的 CI 檢查：Check linked issues 和 Lint Code Base
建議使用壓縮合併；分支在合併後自動刪除

完整工作流程規則請參閱 CONTRIBUTING.md。