Spectral リンティングルール

本プロジェクトでは、OAS3 リンティングに Spectral を使用しており、CI/外部ツール用とパイプラインのカスタムロジック用を分離した二段構成のアーキテクチャを採用しています。

二段構成アーキテクチャ

`.spectral.yaml` — ベース設定

GitHub Super-Linter およびその他の外部 CI ツールで使用されます。spectral:oas（組み込みの OAS ルールセット）を継承します。カスタム関数は含まれていません。これにより、spectral/functions/ ディレクトリにアクセスせずに Spectral を実行するツールとの互換性が保たれます。

extends:
  - "spectral:oas"

rules:
  path-params: "off"
  operation-tags: warn
  oas3-api-servers: warn
  info-contact: warn
  oas3-unused-component: warn
  operation-operationId-unique: error
  oas3-valid-schema-example: error
  no-script-tags-in-markdown: warn
  operation-description: info
  info-description: info

`spectral-pipeline.yaml` — パイプライン設定

scripts/spectral_lint.py（discover モードと gate モードの両方）で使用されます。ベース設定を継承し、カスタム f5-path-params 関数を追加します：

extends:
  - "./.spectral.yaml"

functionsDir: "./spectral/functions"
functions:
  - f5-path-params

rules:
  f5-path-params:
    description: "Path parameters must be declared and used"
    message: "{{error}}"
    severity: error
    given: "$.paths[*]"
    then:
      function: f5-path-params

`path-params` が無効化されている理由

Spectral の組み込み path-params ルールは、{metadata.namespace} や {metadata.name} のようなドット付きパラメータ名を使用する F5 XC API を誤って検出します。組み込みルールはパラメータ名のドットを解析できないため、未宣言として報告してしまいます。

カスタム f5-path-params 関数（spectral/functions/f5-path-params.js）は、{placeholder} の完全な内容を宣言されたパラメータ名と照合することで、ドット付き名前を正しく処理します。パスレベルとオペレーションレベルの両方のパラメータを確認し、双方向でエラーを報告します：

URL パス内のプレースホルダーに対応するパラメータ宣言がない場合
宣言されたパスパラメータが URL パス内に存在しない場合

ルールリファレンス

自動修正可能なルール

これらのルールは、違反が検出された際にリコンサイラーによって自動修正されます。各修正の詳細については適用される修正を参照してください。

ルール	重大度	修正メソッド	説明
`oas3-api-servers`	warn	`_add_servers`	仕様に `servers` ブロックが必要
`info-contact`	warn	`_add_contact`	`info` に `contact` を含める必要がある
`operation-tags`	warn	`_add_tags`	すべてのオペレーションに少なくとも1つのタグが必要
`oas3-unused-component`	warn	`_remove_unused_component`	未参照のコンポーネントスキーマがないこと
`operation-operationId-unique`	error	`_deduplicate_operation_id`	すべての operationId が一意でなければならない
`oas3-valid-schema-example`	error	`_fix_schema_example`	examples/defaults がスキーマと一致する必要がある
`no-script-tags-in-markdown`	warn	`_strip_script_tags`	description に `<script>` タグがないこと
`f5-path-params`	error	—	パスパラメータが宣言され使用されている必要がある

修正不可能なルール

これらのルールは、意味のある自動修正ができないため info 重大度にダウングレードされています：

ルール	重大度	説明
`operation-description`	info	オペレーションには description があるべき
`info-description`	info	API info には description があるべき

パイプライン統合

Spectral アダプター（scripts/spectral_lint.py）は2つのモードで動作します：

Discover モード（リコンサイル前）

make spectral-lint
# Equivalent to: python -m scripts.spectral_lint --mode discover

specs/original/ をスキャンし、reports/spectral_report.json を出力します。リコンサイラーはこのレポートをバリデーションレポートとともに消費します。

Gate モード（リコンサイル後）

make spectral-gate
# Equivalent to: python -m scripts.spectral_lint --mode gate

release/specs/ をスキャンし、reports/spectral_gate_report.json を出力します。違反が設定されたしきい値を超えた場合、終了コード 1 を返します。

違反のマッピング

Spectral の違反は3つのサブタイプを持つ Discrepancy オブジェクトに変換されます：

Spectral ルールカテゴリ	DiscrepancyType	ルール例
必須要素の欠如	`SPECTRAL_MISSING`	`oas3-api-servers`、`info-contact`、`operation-tags`
既存要素の不正	`SPECTRAL_INVALID`	`oas3-valid-schema-example`、`no-script-tags-in-markdown`
デッドコード	`SPECTRAL_UNUSED`	`oas3-unused-component`