กฎการตรวจสอบด้วย Spectral

โปรเจกต์นี้ใช้ Spectral สำหรับการตรวจสอบ OAS3 ด้วยสถาปัตยกรรมแบบสองคอนฟิกที่แยก CI/เครื่องมือภายนอกออกจากลอจิกกำหนดเองของไปป์ไลน์

สถาปัตยกรรมแบบสองคอนฟิก

.spectral.yaml — คอนฟิกพื้นฐาน

ใช้โดย GitHub Super-Linter และเครื่องมือ CI ภายนอกใดๆ ขยายจาก spectral:oas (ชุดกฎ OAS ในตัว) ไม่มีฟังก์ชันกำหนดเอง — เพื่อให้เข้ากันได้กับเครื่องมือที่รัน Spectral โดยไม่สามารถเข้าถึงไดเรกทอรี spectral/functions/

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

กฎ path-params ในตัวของ Spectral แจ้งเตือนผิดพลาดสำหรับ F5 XC API ที่ใช้ชื่อพารามิเตอร์แบบมีจุดเช่น {metadata.namespace} และ {metadata.name} กฎในตัวไม่สามารถแยกวิเคราะห์จุดในชื่อพารามิเตอร์ได้ จึงรายงานว่าเป็นพารามิเตอร์ที่ไม่ได้ประกาศ

ฟังก์ชันกำหนดเอง f5-path-params (spectral/functions/f5-path-params.js) จัดการชื่อแบบมีจุดได้อย่างถูกต้องโดยจับคู่เนื้อหาทั้งหมดของ {placeholder} กับชื่อพารามิเตอร์ที่ประกาศไว้ ฟังก์ชันนี้ตรวจสอบพารามิเตอร์ทั้งระดับ path และระดับ operation และรายงานข้อผิดพลาดในทั้งสองทิศทาง:

• placeholder ใน URL path ที่ไม่มีการประกาศพารามิเตอร์ที่ตรงกัน
• พารามิเตอร์ path ที่ประกาศแล้วแต่ไม่ปรากฏใน URL path

อ้างอิงกฎ

กฎที่แก้ไขอัตโนมัติได้

กฎเหล่านี้จะถูกแก้ไขอัตโนมัติโดย reconciler เมื่อตรวจพบการละเมิด ดู การแก้ไขที่ดำเนินการ สำหรับรายละเอียดของแต่ละการแก้ไข

กฎ	ความรุนแรง	วิธีการแก้ไข	คำอธิบาย
oas3-api-servers	warn	_add_servers	สเปคต้องมีบล็อก servers
info-contact	warn	_add_contact	info ต้องมี contact
operation-tags	warn	_add_tags	ทุก operation ต้องมีอย่างน้อยหนึ่ง tag
oas3-unused-component	warn	_remove_unused_component	ไม่มี component schema ที่ไม่ถูกอ้างอิง
operation-operationId-unique	error	_deduplicate_operation_id	operationId ทั้งหมดต้องไม่ซ้ำกัน
oas3-valid-schema-example	error	_fix_schema_example	ตัวอย่าง/ค่าเริ่มต้นต้องตรงกับ schema
no-script-tags-in-markdown	warn	_strip_script_tags	ไม่มีแท็ก <script> ใน description
f5-path-params	error	—	พารามิเตอร์ path ต้องถูกประกาศและใช้งาน

หมายเหตุ

f5-path-params เป็นกฎระดับความรุนแรง error แต่ไม่ได้ถูกแก้ไขอัตโนมัติ การละเมิดบ่งชี้ถึงข้อบกพร่องของสเปคที่แท้จริงซึ่งต้องมีการตรวจสอบด้วยตนเอง

กฎที่แก้ไขไม่ได้

กฎเหล่านี้ถูกลดระดับความรุนแรงเป็น info เนื่องจากไม่สามารถแก้ไขอัตโนมัติได้อย่างมีความหมาย:

กฎ	ความรุนแรง	คำอธิบาย
operation-description	info	Operation ควรมี description
info-description	info	ข้อมูล API ควรมี description

การรวมเข้ากับไปป์ไลน์

Spectral adapter (scripts/spectral_lint.py) ทำงานในสองโหมด:

โหมด Discover (ก่อน Reconcile)

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

สแกน specs/original/ และเขียน reports/spectral_report.json reconciler จะใช้รายงานนี้ร่วมกับรายงานการตรวจสอบความถูกต้อง

โหมด Gate (หลัง Reconcile)

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

สแกน release/specs/ และเขียน reports/spectral_gate_report.json คืนค่า exit code 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