パイプライン概要

パイプラインはGitHub Actions（validate-and-release.yml）により毎日UTC 6時に実行され、またscripts/、config/、またはpyproject.tomlに変更を加えるmainブランチへのプッシュごとにも実行されます。リリースの強制やライブAPIテストのスキップなどのオプションを指定して手動でトリガーすることも可能です。

パイプラインのステージ

 Download         Validate          Spectral Lint
 ┌──────┐        ┌──────────┐      ┌─────────────┐
 │ Fetch │───────▶│Schemathesis│────▶│  Discover   │
 │ specs │        │Constraints│     │  violations │
 └──────┘        └──────────┘      └─────────────┘
                                          │
                 Spectral Gate       Reconcile
                ┌─────────────┐    ┌──────────┐
                │  Enforce    │◀───│Apply fixes│
                │  thresholds │    │to specs   │
                └─────────────┘    └──────────┘
                       │
                    Release
                 ┌──────────┐
                 │  Package  │
                 │  & tag    │
                 └──────────┘

1. ダウンロード

scripts/download.pyはdocs.cloud.f5.comから公式F5 XC OpenAPI仕様のZIPを取得します。HTTP ETagヘッダーを使用した条件付きGETリクエストにより、アップストリームバンドルが変更されていない場合はダウンロードをスキップします。展開されたJSON仕様はspecs/original/に配置されます。

2. 検証

scripts/validate.pyはライブF5 XC APIに対して2種類のテストを実行します：

Schemathesis — 仕様に基づいてランダムな有効/無効ペイロードを生成し、APIが仕様の制約と一致しているかを確認するプロパティベースのテスト。
制約検証 — OpenAPIの全10カテゴリの制約（文字列長、パターン、数値範囲、必須フィールド、列挙型、配列範囲、オブジェクト構造、合成、依存関係、データ型）に対するターゲットテスト。

不一致はreports/validation_report.jsonに書き出されます。

3. Spectralリント（検出）

scripts/spectral_lint.py --mode discoverはspectral-pipeline.yamlを使用して、オリジナル仕様に対してSpectral CLIを実行します。これによりOAS3の品質問題を検出します — serversブロックの欠落、連絡先情報の欠落、タグ付けされていないオペレーション、未使用のコンポーネントスキーマ、重複するoperationId、無効なexample、descriptionに含まれるscriptタグなどです。

違反はDiscrepancyオブジェクトに変換され、reports/spectral_report.jsonに書き出されます。完全なルールセットについてはSpectralルールを参照してください。

4. 調整

scripts/reconcile.pyは両方のレポートファイルを読み取り、すべての仕様に修正を適用します：

制約の修正は、観測されたAPIの動作に基づいてスキーマ制約を調整します（緩和、厳格化、追加、削除）。適用された修正を参照してください。
Spectralの修正は、servers、連絡先情報、タグ、セキュリティメタデータを仕様に追加し、不要なコンポーネントを削除します。
セキュリティメタデータは、Spectralがフラグを立てなかった場合でも、security_scheme設定が存在する限り常に注入されます。

修正された仕様はrelease/specs/に書き出され、保存前にopenapi-spec-validatorで検証されます。修正された仕様が検証に失敗した場合、フォールバックとしてオリジナルが使用されます。

5. Spectralゲート

scripts/spectral_lint.py --mode gateはrelease/specs/内の調整済み仕様に対してSpectralを再実行します。ゲートは、設定可能なしきい値（validation.yamlのspectral.gate.max_errorsおよびspectral.gate.max_warnings）に対してエラー数と警告数をチェックします。

6. リリース

scripts/release.pyは調整済み仕様をバージョン付きZIPアーカイブにパッケージ化します。バージョンはアップストリーム仕様メタデータの日付から導出されるYYYY.MM.DD-<patch>形式を使用します。リリースには以下が含まれます：

個別のドメイン仕様ファイル（268個のJSONファイル）
すべてのドメインを統合したマージ済みopenapi.json
適用されたすべての修正を一覧するCHANGELOG.md
VALIDATION_REPORT.mdサマリー

CIジョブはZIPを添付したGitHub Releaseを作成し、v<version>でタグ付けします。コンテンツハッシュにより、変更がない場合の重複リリースを防止します。

ドキュメントの更新

並行するCIジョブがscripts/generate_docs.pyを使用して検証レポートからdocs/01-validation-report.mdxを生成し、内容に変更があった場合はPRをオープンします。