การแก้ไขที่นำไปใช้กับสเปคต้นทาง

ตัวปรับประสาน (scripts/reconcile.py) ใช้การแก้ไข 4 หมวดหมู่กับสเปคต้นทาง การแก้ไขข้อจำกัดจะเปลี่ยนสัญญา API ให้ตรงกับพฤติกรรมที่สังเกตได้ การแก้ไขอื่นๆ ทั้งหมดเป็นการเปลี่ยนแปลงเฉพาะเมตาดาต้าและไม่เปลี่ยนแปลงสัญญา API

การแก้ไขข้อจำกัด

การแก้ไขเหล่านี้ปรับข้อจำกัดของ OpenAPI schema เพื่อให้สเปคตรงกับสิ่งที่ API จริงบังคับใช้ การแก้ไขแต่ละรายการขับเคลื่อนโดยอ็อบเจกต์ Discrepancy ที่สร้างขึ้นระหว่างการตรวจสอบ

กลยุทธ์	ทริกเกอร์	สิ่งที่ทำ	การเปลี่ยนแปลงสัญญา
Relax	SPEC_STRICTER	สเปคปฏิเสธค่าที่ API ยอมรับ ลด minLength/minimum เพิ่ม maxLength/maximum เพิ่มค่า enum ที่ขาดหายไป	ใช่ — ขยายค่าที่ยอมรับ
Tighten	SPEC_LOOSER	สเปคยอมรับค่าที่ API ปฏิเสธ เพิ่ม minLength/minimum ลด maxLength/maximum จำกัด enum เฉพาะค่าที่สังเกตได้	ใช่ — จำกัดค่าที่ยอมรับ
Add	MISSING_CONSTRAINT	API บังคับใช้ข้อจำกัดที่ไม่ได้บันทึกไว้ในสเปค เพิ่มข้อจำกัดลงใน schema	ใช่ — เพิ่มข้อจำกัดใหม่
Remove	EXTRA_CONSTRAINT	สเปคประกาศข้อจำกัดที่ API ละเว้น ลบข้อจำกัดออกจาก schema	ใช่ — ลบข้อจำกัด

คำเตือน

การแก้ไขข้อจำกัดเปลี่ยนสัญญา API จะนำไปใช้เฉพาะเมื่อมีหลักฐานสนับสนุนจาก Schemathesis หรือการทดสอบตรวจสอบข้อจำกัดกับ API จริงเท่านั้น

ประเภทข้อจำกัดที่รองรับ

10 หมวดหมู่ข้อจำกัด OpenAPI ที่ทดสอบและแก้ไข:

• ความยาวสตริง — minLength, maxLength
• รูปแบบ — pattern (regex)
• ขอบเขตตัวเลข — minimum, maximum, exclusiveMinimum, exclusiveMaximum
• ฟิลด์ที่จำเป็น — required
• ค่า Enum — enum
• ขอบเขตอาร์เรย์ — minItems, maxItems, uniqueItems
• โครงสร้างอ็อบเจกต์ — additionalProperties, properties, propertyNames
• การประกอบ — oneOf, anyOf, allOf
• การอ้างอิง — dependentRequired, dependentSchemas
• ประเภทข้อมูล — type, format

การเพิ่มคุณภาพจาก Spectral

การแก้ไขเหล่านี้แก้ไขปัญหาคุณภาพ OAS3 ที่พบโดยการตรวจสอบ Spectral เพิ่มหรือแก้ไขเมตาดาต้าโดยไม่เปลี่ยนพฤติกรรม API

การเพิ่มบล็อก Servers

กฎ: oas3-api-servers | การเปลี่ยนแปลงสัญญา: ไม่

เพิ่มเทมเพลต URL ของ F5 XC tenant ลงในสเปคที่ไม่มีบล็อก servers:

"servers": [{
  "url": "https://{tenant}.console.ves.volterra.io",
  "description": "F5 Distributed Cloud API",
  "variables": {
    "tenant": {
      "default": "example-tenant",
      "description": "Your F5 XC tenant name"
    }
  }
}]

URL ของเซิร์ฟเวอร์และค่าตัวแปรมาจาก spectral.servers ใน validation.yaml

การเพิ่มข้อมูลติดต่อ

กฎ: info-contact | การเปลี่ยนแปลงสัญญา: ไม่

เพิ่มข้อมูลติดต่อลงใน info.contact สำหรับสเปคที่ไม่มี:

"contact": {
  "name": "F5 Distributed Cloud",
  "url": "https://docs.cloud.f5.com",
  "email": "support@f5.com"
}

ค่ามาจาก spectral.contact ใน validation.yaml

การสร้างแท็กของ Operation

กฎ: operation-tags | การเปลี่ยนแปลงสัญญา: ไม่

สร้างแท็กจากคำนำหน้าเส้นทาง URL สำหรับ operation ที่ไม่มีแท็ก สำหรับเส้นทางเช่น /api/config/namespaces/{namespace}/healthchecks แท็กจะเป็น config (ส่วนที่ไม่ใช่พารามิเตอร์ลำดับที่สอง) แท็กจะถูกเพิ่มทั้งในอาร์เรย์ tags ของ operation และรายการ tags ระดับสเปค

การลบคอมโพเนนต์ที่ไม่ได้ใช้

กฎ: oas3-unused-component | การเปลี่ยนแปลงสัญญา: ไม่

ลบ component schema ออกจาก components.schemas ที่ไม่ได้ถูกอ้างอิงที่ใดในสเปค ลดขนาดสเปคโดยไม่ส่งผลกระทบต่อ operation ใดๆ

การกำจัดค่า OperationId ซ้ำ

กฎ: operation-operationId-unique | การเปลี่ยนแปลงสัญญา: ไม่

ต่อท้าย HTTP method เป็นส่วนต่อท้าย (เช่น ListItems_get) เมื่อ operation หลายตัวมี operationId เดียวกัน ทำให้แต่ละ operationId ไม่ซ้ำกันสำหรับตัวสร้างโค้ด

การลบ Example/Default ที่ไม่ถูกต้อง

กฎ: oas3-valid-schema-example | การเปลี่ยนแปลงสัญญา: ไม่

ลบค่า example หรือ default ออกจาก schema เมื่อค่าไม่สอดคล้องกับข้อจำกัดของ schema เอง (ประเภทผิด ออกนอกช่วง ฯลฯ) ป้องกันตัวสร้างโค้ดจากการผลิต payload ตัวอย่างที่ไม่ถูกต้อง

การลบแท็ก Script

กฎ: no-script-tags-in-markdown | การเปลี่ยนแปลงสัญญา: ไม่

ลบแท็ก <script> ออกจากฟิลด์ description โดยใช้การแทนที่ด้วย regex สเปคต้นทางบางตัวมีแท็ก script ที่ถูกแทรกเข้ามาซึ่งทำให้ตัวแสดงผลเอกสารเสียหาย

เมตาดาต้าความปลอดภัย

การเปลี่ยนแปลงสัญญา: ไม่ (เฉพาะเอกสารเท่านั้น)

ทุกสเปคจะได้รับ security scheme apiKeyAuth หากยังไม่มี สิ่งนี้จะถูกเพิ่มเข้าไปเสมอโดยไม่คำนึงว่า Spectral จะตั้งค่าสถานะหรือไม่

"components": {
  "securitySchemes": {
    "apiKeyAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization",
      "description": "F5 XC API Token (format: APIToken <token>)"
    }
  }
},
"security": [{ "apiKeyAuth": [] }]

นิยามของ scheme มาจาก spectral.security_scheme ใน validation.yaml สิ่งนี้บอกผู้ใช้ API ว่าจะตรวจสอบสิทธิ์อย่างไร แต่ไม่เปลี่ยนพฤติกรรมรันไทม์

การจัดรูปแบบ JSON

การเปลี่ยนแปลงสัญญา: ไม่

ไฟล์ JSON สเปคเอาต์พุตทั้งหมดผ่านตัวบีบอัดอาร์เรย์ที่เข้ากันได้กับ Biome (_compact_short_arrays ใน scripts/utils/spec_loader.py) อาร์เรย์สั้นที่พอดีภายใน 120 ตัวอักษรจะถูกยุบเป็นบรรทัดเดียว:

// Before
"enum": [
  "ACTIVE",
  "INACTIVE"
]

// After
"enum": ["ACTIVE", "INACTIVE"]

อาร์เรย์ที่เกินเกณฑ์ความยาวบรรทัดจะยังคงเป็นหลายบรรทัด

ลำดับความสำคัญของการแก้ไข

เมื่อกลยุทธ์การแก้ไขหลายตัวสามารถนำไปใช้ได้ ตัวปรับประสานจะใช้ลำดับความสำคัญที่กำหนดค่าใน reconciliation.priority:

1. existing — ใช้ข้อจำกัดของสเปคที่มีอยู่หากถูกต้อง
2. discovery — ใช้พฤติกรรมของ API จริงที่ค้นพบ
3. inferred — อนุมานจากรูปแบบข้าม endpoint ที่คล้ายกัน

ทุกสเปคที่แก้ไขแล้วจะถูกตรวจสอบด้วย openapi-spec-validator หลังจากใช้การแก้ไขทั้งหมด หากการตรวจสอบล้มเหลว สเปคต้นฉบับจะถูกใช้เป็นทางเลือกสำรองและการแก้ไขจะถูกบันทึกเป็นข้อผิดพลาด