開発ガイド

このガイドでは、F5 XC API エンリッチメントパイプラインの開発ワークフローについて説明します。

クイックスタート

初回セットアップ

# Clone the repository
git clone https://github.com/f5-sales-demo/api-specs-enriched.git
cd api-specs-enriched

# Create virtual environment and install dependencies
make install

# Install pre-commit hooks
make pre-commit-install

# Download specs and run pipeline
make build

# Preview documentation locally
make serve

日常的な開発

# Quick rebuild (uses cached specs)
make rebuild

# Run all quality checks
make pre-commit-run

# Preview documentation
make serve

アーキテクチャの概要

2フォルダ構成

┌─────────────────────┐     ┌─────────────────────────────┐
│   specs/original/   │────▶│   docs/specifications/api/  │
│   (READ-ONLY)       │     │   (GENERATED)               │
│   - Downloaded      │     │   - Domain specs            │
│   - Gitignored      │     │   - Master spec             │
│   - ETag cached     │     │   - GitHub Pages            │
└─────────────────────┘     └─────────────────────────────┘

パイプラインフロー

Download (ETag) → Enrich → Normalize → Merge → Lint → Serve
     │              │          │         │       │
     ▼              ▼          ▼         ▼       ▼
 270 specs     Branding    Fix refs   23 domains  Spectral
             + Grammar    + Types    + Master     rules

ディレクトリ構造

ディレクトリ	用途	Git ステータス
specs/original/	F5 ソーススペック	Gitignored
specs/discovered/	API ディスカバリー出力	トラッキング済み (openapi.json, session.json)
docs/specifications/api/	生成されたドメインスペック	Gitignored
scripts/	Python パイプラインスクリプト	トラッキング済み
config/	パイプライン設定	トラッキング済み
reports/	生成されたレポート	Gitignored

ワークフローパターン

1. ディスカバリーワークフロー

前提条件:

• F5 XC 環境への VPN 接続
• 有効な API 認証情報

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

# Run discovery
make discover

# View results
jq '.statistics' specs/discovered/session.json

# Commit for CI/CD
make push-discovery

ディスカバリーによって取得される情報:

• 実際の必須/オプションフィールド
• ライブレスポンスからの列挙値
• デフォルト値
• パターンバリデーション
• レスポンスの例

2. リリースワークフロー

リリースは自動化されています。

1. 毎日のスケジュール (UTC 午前 6 時) またはメインへのプッシュがワークフローをトリガー
2. ETag チェックにより F5 スペックの変更を確認
3. パイプラインがスペックを処理・エンリッチ
4. バージョンは git タグから算出: git describe --tags --abbrev=0
5. 直接コミット + タグ作成 (バージョンバンプ PR なし)
6. 変更ログ付きの GitHub Release を作成
7. ドキュメントを GitHub Pages にデプロイ

バージョンバンプルール:

条件	バンプ種別	例
コミットに [major]	メジャー	1.0.0 → 2.0.0
コミットに BREAKING CHANGE	メジャー	1.0.0 → 2.0.0
新しいドメインスペックの追加	マイナー	1.0.0 → 1.1.0
その他の変更	パッチ	1.0.0 → 1.0.1

3. 開発ワークフロー

# Create feature branch
git checkout -b feature/my-change

# Make changes to config or scripts

# Test locally
make pipeline
make lint

# Commit (pre-commit hooks run automatically)
git add .
git commit -m "feat: add new enrichment rule"

# Push and create PR
git push -u origin feature/my-change
gh pr create

ディスカバリーの詳細

ディスカバリーとは？

ディスカバリーはライブの F5 XC API を探索し、以下の情報を取得します。

• 未ドキュメントの制約: OpenAPI にマークされていない必須フィールド
• 実際の列挙値: 本番環境で確認された実値
• デフォルトの動作: フィールドが省略された際にサーバーが適用する値
• レスポンスパターン: 実際のデータ形状

ディスカバリー設定

config/discovery.yaml

discovery:
  exploration:
    namespaces:
      - "system"
      - "shared"
    methods:
      - "GET"
      - "OPTIONS"
    max_endpoints_per_run: 500

  schema_inference:
    sample_size: 3
    detect_patterns: true
    detect_constraints: true

ディスカバリー拡張

ディスカバリーはスペックに x-discovered-* 拡張を追加します。

{
  "properties": {
    "name": {
      "type": "string",
      "x-discovered-required": true,
      "x-discovered-pattern": "^[a-z][a-z0-9-]*$",
      "x-discovered-examples": ["my-app", "prod-lb"]
    }
  }
}

制約分析レポート

reports/constraint-analysis.md

make constraint-report

リリースプロセス

リリースパッケージの内容

f5xc-api-specs-v1.0.14.zip
├── openapi.json       # Master combined spec
├── openapi.yaml       # YAML format
├── domains/           # Individual domain specs
│   ├── api_security.json
│   ├── load_balancer.json
│   └── ...
├── index.json         # Metadata
├── CHANGELOG.md       # Release notes
└── README.md          # Usage instructions

ワークフローの手動トリガー

gh workflow run sync-and-enrich.yml
gh run watch

設定ガイド

エンリッチメント設定

config/enrichment.yaml

enrichment:
  branding:
    replacements:
      "Volterra": "F5 Distributed Cloud"
      "VES": "F5 XC"

  acronyms:
    API: "Application Programming Interface"
    DNS: "Domain Name System"

  grammar:
    enabled: true
    language_tool: true

正規化設定

config/normalization.yaml

normalization:
  orphan_refs:
    fix: true
    remove_if_unresolvable: true

  empty_operations:
    remove: true

  type_standardization:
    enabled: true

Spectral リントルール

config/spectral.yaml

extends:
  - spectral:oas

rules:
  operation-operationId: error
  operation-tags: warn

OpenAPI 拡張

エンリッチメントパイプラインはベンダー拡張を使用して、バリデーションおよびデフォルト値のメタデータを埋め込みます。

拡張カテゴリ

拡張	意味	影響
x-f5xc-server-default	フィールドが省略された際に F5 XC API サーバーがこの値を適用する	フィールドはオプション。省略するとドキュメント化されたデフォルト動作が適用される
x-f5xc-recommended-value	F5 XC Web コンソールが新規リソース作成時にこの値を事前入力する	フィールドにサーバーデフォルトはないが、この値が典型的な設定を表す
x-f5xc-recommended-oneof-variant	F5 XC コンソールがこの OneOf バリアントを事前選択する	複数の相互排他的なオプションが存在する場合の典型的な選択肢を識別する
x-f5xc-conflicts-with	このフィールドと同時に使用できない他のプロパティを列挙する	プロパティは OneOf グループの一部。競合するプロパティのうち 1 つのみ指定可能

必須フィールド拡張

拡張	ソース	用途
x-ves-required: "true"	F5 XC オリジナルスペック	フィールドにゼロ値または空値以外の値が必要
x-f5xc-required-for	エンリッチメントパイプライン	コンテキスト固有の必須ステータス

x-f5xc-required-for のコンテキスト:

• create: リソース作成時に必須
• update: リソース更新時に必須
• minimum_config: 最小限の有効な設定に必須

デフォルト値および OneOf 拡張

拡張	用途
x-f5xc-server-default: true	サーバー適用デフォルトのマーク
x-f5xc-recommended-value	F5 XC コンソールの事前入力値
x-f5xc-recommended-oneof-variant	推奨される OneOf バリアント
x-f5xc-conflicts-with	他の OneOf プロパティとの相互排他性

x-f5xc-server-default

型: boolean

true の場合、付随する default 値が F5 XC API サーバーによって強制適用されることを示します。この拡張を持つフィールドは API リクエストから安全に省略できます — サーバーがデフォルト値を自動的に適用します。

use_http2:
  type: boolean
  default: false
  x-f5xc-server-default: true

x-f5xc-recommended-value

型: any (フィールドの型に一致)

F5 XC Web コンソールが事前入力デフォルトとして使用する値を指定します。この値はサーバーで強制適用されるものではありませんが、コンソール経由で作成される新規リソースの典型的な初期設定を表します。

timeout:
  type: integer
  x-f5xc-recommended-value: 3

x-f5xc-recommended-oneof-variant

型: object (グループ名からバリアント名へのマップ)

相互排他的なフィールドグループを持つスキーマにおいて、デフォルトまたは最も一般的な選択肢であるバリアントを識別します。キーは OneOf グループ名、値は推奨バリアントのフィールド名です。

healthcheckCreateSpecType:
  type: object
  x-f5xc-recommended-oneof-variant:
    health_check: "http_health_check"

x-f5xc-conflicts-with

型: 文字列の array

追加バージョン: v3.2.0 (Issue #494)

OneOf グループメンバー間の相互排他的な関係を宣言します。x-ves-oneof-field-* 拡張から自動導出されます。これにより、下流ツール (Terraform、CLI、MCP) がランタイムではなくスキーマレベルで競合を検証できます。

host_header:
  type: string
  x-f5xc-conflicts-with: ["use_origin_server_name"]

use_origin_server_name:
  type: object
  x-f5xc-conflicts-with: ["host_header"]

ユースケース:

• Terraform プロバイダーがバリデーションルールを生成できる
• CLI ツールが競合するフィールドの組み合わせについて警告できる
• AI アシスタントが正しい OneOf 設定を生成できる
• IDE 拡張機能が競合を考慮したオートコンプリートを提供できる

ソース: パイプラインエンリッチメント時に F5 ネイティブの x-ves-oneof-field-* 拡張から自動導出されます。

バリデーションルールの影響

エンリッチャーは x-ves-validation-rules を検査して必須ステータスを推定します。

ルール	影響
ves.io.schema.rules.message.required: "true"	フィールドは必須
ves.io.schema.rules.uint32.gte: N	N >= 1 かつサーバーデフォルトがない場合、フィールドは必須
ves.io.schema.rules.repeated.min_items: N	N >= 1 の場合、配列には少なくとも N 個の要素が必要
ves.io.schema.rules.string.min_bytes: N	N >= 1 の場合、文字列には少なくとも N バイトが必要

サーバー適用デフォルトを持つリソース

一部のリソースはサーバーがデフォルト値を適用するため、空のスペックを受け入れます。

リソース	サーバー適用デフォルト
app_firewall	monitoring: \{\}, default_detection_settings: \{\}
rate_limiter	limits: [], user_identification: []
api_definition	swagger_specs: [], デフォルト api_groups
healthcheck	jitter: 0, jitter_percent: 0, ネストされた http_health_check デフォルト

これらのリソースでは、x-ves-required が true の場合でも x-f5xc-required-for.create が false になることがあります。

デフォルト値のパターン

パターン	型	例
\{\}	空オブジェクト (選択選択)	monitoring: \{\}
[]	空配列	expected_status_codes: []
0	数値	jitter: 0
""	文字列	expected_response: ""
false	ブール値	use_http2: false

発見されたデフォルトの追加

1. API 経由で最小限のスペックを使用して F5 XC でリソースを作成
2. リソースを読み返してサーバー適用値を確認
3. config/discovered_defaults.yaml にデフォルトをドキュメント化
4. パイプラインを実行: make pipeline
5. 以下で確認: jq '.components.schemas | to_entries[] | select(.key | contains("resource_name"))'

トラブルシューティング

pre-commit に時間がかかりすぎる

パイプラインは一貫性を確保するためにすべてのコミットで実行されます。作業中のコミットの場合:

git commit --no-verify -m "WIP: work in progress"
# Run before final commit: make pre-commit-run

ディスカバリーが失敗する

# Check VPN
ping your-tenant.console.ves.volterra.io

# Check credentials
echo $F5XC_API_TOKEN | head -c 10

# Check API URL format
echo $F5XC_API_URL
# Format: https://tenant.console.ves.volterra.io/api

生成されたスペックのリントエラー

# Check lint report
cat reports/lint-report.json | jq '.errors'

出力ファイルではなく、エンリッチメント/正規化設定で問題を修正してください。

バージョンシステム

バージョンは git タグから導出されます (例: v2.0.38)。これにより、並行 PR でのマージ競合を引き起こしていた競合状態が解消されます。

# Version is calculated dynamically from git tags
from scripts.utils.version_calculator import get_version_from_tags
version = get_version_from_tags()  # Returns "2.0.38"

クローン後にスペックが見つからない

生成されたスペックは gitignored になっています。

make build  # Downloads and generates everything

大きなファイルがブロックされる

.pre-commit-config.yaml に除外設定を追加してください。

- id: check-added-large-files
  exclude: ^path/to/large/file\.json$

クイックリファレンス

Make ターゲット

ターゲット	説明
make build	フルビルド (ダウンロード + パイプライン)
make rebuild	クイックリビルド (ダウンロードをスキップ)
make download	スペックのダウンロード (ETag キャッシュ使用)
make download-force	強制ダウンロード
make pipeline	エンリッチメントパイプラインの実行
make lint	Spectral リント
make serve	ローカルドキュメントサーバー
make discover	API ディスカバリー (VPN 必須)
make push-discovery	ディスカバリーデータのコミット
make clean	生成ファイルの削除
make pre-commit-run	すべての品質チェックの実行

環境変数

変数	用途
F5XC_API_URL	F5 XC テナント API URL
F5XC_API_TOKEN	API 認証トークン

主要ファイル

ファイル	用途
.etag	最後にダウンロードした ETag
CHANGELOG.md	自動生成された変更ログ
config/enrichment.yaml	エンリッチメントルール
config/normalization.yaml	正規化ルール
config/discovery.yaml	ディスカバリー設定
config/spectral.yaml	リントルール
scripts/utils/version_calculator.py	タグベースのバージョン算出

注意: バージョンは .version ファイルではなく、git タグから導出されます (例: v2.0.38)。