Spectral 檢查規則

本專案使用 Spectral 進行 OAS3 檢查，採用雙設定架構將 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（探索模式與閘門模式）使用。繼承基礎設定並新增自訂 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`	每個操作必須至少有一個標籤
`oas3-unused-component`	warn	`_remove_unused_component`	不得有未被參照的元件結構定義
`operation-operationId-unique`	error	`_deduplicate_operation_id`	所有 operationId 必須唯一
`oas3-valid-schema-example`	error	`_fix_schema_example`	範例/預設值必須符合其結構定義
`no-script-tags-in-markdown`	warn	`_strip_script_tags`	描述中不得包含 `<script>` 標籤
`f5-path-params`	error	—	路徑參數必須被宣告且使用

不可修復的規則

這些規則被降級為 info 嚴重性，因為無法進行有意義的自動修復：

規則	嚴重性	說明
`operation-description`	info	操作應包含描述
`info-description`	info	API 資訊應包含描述

管線整合

Spectral 適配器（scripts/spectral_lint.py）以兩種模式執行：

探索模式（協調前）

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

掃描 specs/original/ 並寫入 reports/spectral_report.json。協調器會連同驗證報告一起使用此報告。

閘門模式（協調後）

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

掃描 release/specs/ 並寫入 reports/spectral_gate_report.json。若違規數量超過設定的閾值，將回傳結束代碼 1。

違規對應

Spectral 違規會被轉換為具有三種子類型的 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`