開発ガイド

セットアップ

# クローンして開発用依存関係をインストール
git clone https://github.com/f5-sales-demo/api-specs.git
cd api-specs
make dev-install

# Spectral CLI をインストール（リンティングステージに必要）
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        # 上記3つすべて（CI で使用）

インストール済みの場合、プリコミットフックはコミット時に自動的に実行されます：

make pre-commit-install   # git フックをインストール
make pre-commit           # すべてのフックを手動で実行

プロジェクト構成

scripts/
  download.py           # ステージ 1: F5 から仕様を取得
  validate.py           # ステージ 2: ライブ API テスト
  spectral_lint.py      # ステージ 3/5: Spectral リンティングアダプター
  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."""
    # spec をインプレースで変更
    # 変更があれば spec を返し、変更不要なら None を返す
    return spec

登録する — _apply_spectral_fix ディスパッチャーに追加します：

spectral_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 に変更があった場合
手動ディスパッチ: 強制リリースまたはドライランのオプション付き

ワークフローには 4 つのジョブがあります：

validate — 仕様をダウンロードし、バリデーション、Spectral リント、リコンサイル、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 を参照してください。