ควบคุมเวอร์ชัน OpenAPI ด้วย Git อย่างไร

OpenAPI spec ของคุณคือสัญญา เมื่อมันไม่สอดคล้องกัน ไคลเอนต์ก็จะเสีย, mock ก็จะล้าสมัย, และการทดสอบก็จะผ่าน API ที่ไม่มีอยู่จริงอีกต่อไป ดังนั้นจงปฏิบัติต่อ spec เหมือนส่วนอื่นๆ ของโค้ดของคุณ: ใส่ไว้ใน Git, แตก branch, ตรวจสอบ, และตรวจสอบความถูกต้องทุกครั้งที่มีการเปลี่ยนแปลง

คู่มือนี้จะอธิบายการควบคุมเวอร์ชัน OpenAPI ด้วย Git ตั้งแต่เริ่มต้น ตั้งแต่ไฟล์อยู่ที่ไหน, วิธีการแตก branch, สิ่งที่ผู้ตรวจสอบมองหาในการเปรียบเทียบ spec, และวิธีการผลักดันการเปลี่ยนแปลงโดยตรงจาก Apidog ในท้ายที่สุดคุณจะมีเวิร์กโฟลว์ที่ทั้งทีมของคุณสามารถเชื่อถือได้

button

ทำไมต้องควบคุมเวอร์ชัน OpenAPI spec ของคุณ

spec ที่อยู่ใน wiki หรือไดรฟ์ที่ใช้ร่วมกันจะไม่มีประวัติ คุณไม่สามารถเห็นว่าใครเปลี่ยน POST /orders payload เมื่อวันอังคารที่แล้ว หรือทำไม Git ช่วยแก้ปัญหานั้นได้

ใส่ openapi.yaml ภายใต้การควบคุมเวอร์ชัน แล้วคุณจะได้สิ่งดีๆ สี่อย่างฟรี:

ประวัติ การเปลี่ยนแปลงทุกครั้งคือ commit ที่มีผู้เขียน, เวลา, และข้อความ
Blame git blame openapi.yaml จะบอกคุณว่าใครเพิ่มฟิลด์ที่จำเป็นนั้นและเมื่อใด
ย้อนกลับ การรวมที่ไม่ดีที่ทำให้สัญญาเสียหาย? ย้อนกลับ commit แล้วคุณก็กลับไปที่ spec ที่ใช้งานได้
การตรวจสอบ การเปลี่ยนแปลง spec ต้องผ่าน pull request ดังนั้นคนที่สองจะเห็นการเปรียบเทียบก่อนที่จะถูกนำไปใช้งาน

นี่คือรากฐานของ เวิร์กโฟลว์ API แบบ Git-native: spec คือซอร์สโค้ด และซอร์สโค้ดอยู่ใน Git

ไฟล์ spec อยู่ที่ไหนใน repo

ทำให้มันง่ายและคาดเดาได้ ทีมส่วนใหญ่จะวางไฟล์ openapi.yaml ไฟล์เดียวที่ root ของ repo หรือในโฟลเดอร์ api/:

my-service/
├── api/
│ └── openapi.yaml
├── src/
└── README.md

เมื่อคุณดูแลเวอร์ชันหลักหลายเวอร์ชันพร้อมกัน ให้แบ่งตามเวอร์ชันโดยมีหนึ่งไฟล์ต่อเวอร์ชันหลัก:

api/
├── api-v1.yaml
└── api-v2.yaml

วิธีนี้ช่วยแยกการเปลี่ยนแปลงที่ส่งผลกระทบ api-v1.yaml ยังคงไม่เปลี่ยนแปลงสำหรับไคลเอนต์ที่มีอยู่ ขณะที่ api-v2.yaml พัฒนาต่อไป นอกจากนี้ยังทำให้การเปรียบเทียบสั้นลงและการตรวจสอบเร็วขึ้น เพราะแต่ละไฟล์เปลี่ยนไปเพียงเหตุผลเดียว การปฏิบัติต่อ spec ด้วยวิธีนี้เป็นแนวคิดหลักเบื้องหลัง API spec as code

เลือกแบบแผนหนึ่งแล้วบันทึกไว้ ผลลัพธ์ที่แย่ที่สุดคือมีสองไฟล์ที่อ้างว่าเป็น “the” spec

กลยุทธ์การแตก branch สำหรับการเปลี่ยนแปลง spec

คุณไม่จำเป็นต้องมีโมเดลการแตก branch พิเศษสำหรับ specs ใช้ซ้ำกับสิ่งที่โค้ดของคุณใช้อยู่แล้ว แตก branch จาก main, ทำการเปลี่ยนแปลง, เปิด PR

รูปแบบการตั้งชื่อที่ทำให้ branch ของ spec สแกนง่าย:

ประเภท Branch	รูปแบบ	ตัวอย่าง
New endpoint	`api/add-<resource>`	`api/add-refunds`
Field change	`api/change-<resource>-<field>`	`api/change-order-status`
Breaking change	`api/breaking-<description>`	`api/breaking-v2-auth`
Fix / cleanup	`api/fix-<description>`	`api/fix-pagination-schema`

คำนำหน้า api/ ส่งสัญญาณว่า “PR นี้เกี่ยวข้องกับสัญญา” ได้อย่างรวดเร็ว ผู้ตรวจสอบและ CI สามารถกรองตามคำนำหน้านี้ได้ สำหรับการเปลี่ยนแปลงที่ส่งผลกระทบ คำนำหน้า breaking- ที่ชัดเจนเป็นธงบ่งชี้ว่าสิ่งนี้ต้องได้รับการตรวจสอบเพิ่มเติมและอาจต้องมีการเพิ่มเวอร์ชัน

รักษา branch ให้มีอายุสั้น branch ของ spec ที่มีอายุสองสัปดาห์จะชนกับการเปลี่ยนแปลงของคนอื่น branch ที่เล็กและเน้นเฉพาะจุดจะรวมกันได้อย่างสะอาด

การตรวจสอบการเปลี่ยนแปลง spec ใน pull request

นี่คือจุดที่การควบคุมเวอร์ชันสร้างคุณค่า PR ของ spec คือการเปลี่ยนแปลงสัญญา และการเปลี่ยนแปลงสัญญาควรได้รับการตรวจสอบอย่างจริงจัง

เขียน YAML ในลักษณะที่เปรียบเทียบง่าย เพื่อให้ผู้ตรวจสอบสามารถอ่านการเปลี่ยนแปลงได้ ไม่ใช่ต้องต่อสู้กับการจัดรูปแบบ:

paths:
 /orders/{orderId}:
 get:
 summary: Get an order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: Order found
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"

การเยื้องที่สอดคล้องกันและคุณสมบัติหนึ่งรายการต่อบรรทัดหมายถึงการเพิ่มฟิลด์เดียวจะแสดงเป็นความแตกต่างหนึ่งบรรทัด นั่นคือเป้าหมาย

สิ่งที่ผู้ตรวจสอบควรตรวจสอบ:

การเปลี่ยนแปลงที่ส่งผลกระทบ (Breaking changes) มีการเพิ่มฟิลด์ที่จำเป็นในคำขอหรือไม่? มีการลบหรือเปลี่ยนชื่อฟิลด์ตอบกลับหรือไม่? enum สูญเสียค่าไปหรือไม่? แต่ละอย่างสามารถทำให้ไคลเอนต์ที่มีอยู่เสียหายได้
ความเข้ากันได้แบบย้อนหลัง (Backward compatibility) ฟิลด์เสริมใหม่และ endpoint ใหม่นั้นปลอดภัย การเปลี่ยนแปลงรูปแบบที่มีอยู่ไม่ปลอดภัย
การตั้งชื่อและความสอดคล้องกัน endpoint ใหม่ตรงกับรูปแบบตัวอักษรและการเป็นพหูพจน์ของ API ส่วนที่เหลือหรือไม่?
ความสมบูรณ์ การดำเนินการใหม่ทุกครั้งต้องมี summary, สกีมาการตอบกลับ, และการตอบกลับข้อผิดพลาด
ตัวอย่าง ตัวอย่างที่สมจริงทำให้เอกสารและ mock มีประโยชน์

สำหรับการตรวจจับการเปลี่ยนแปลงที่ส่งผลกระทบ ให้พึ่งพาเครื่องมือมากกว่าการใช้สายตา ขั้นตอน CI (จะกล่าวถึงด้านล่าง) สามารถเปรียบเทียบ spec ของ PR กับ main และทำให้การ build ล้มเหลวหากพบการเปลี่ยนแปลงที่ไม่เข้ากัน มนุษย์พลาดสิ่งเหล่านี้ได้ แต่เครื่องมือเปรียบเทียบจะไม่พลาด

Commit & push จาก Apidog

การแก้ไข YAML ดิบด้วยมือใช้ได้ แต่โปรแกรมแก้ไขภาพที่มีการตรวจสอบแบบเรียลไทม์จะเร็วกว่าและตรวจจับข้อผิดพลาดได้เร็วกว่า โหมด Spec-First ของ Apidog ให้การซิงค์ Git สองทาง: แก้ไข spec ใน UI, commit, และ push ไปยัง repo ของคุณโดยไม่ต้องออกจากเครื่องมือ ดึงการเปลี่ยนแปลงของเพื่อนร่วมทีมกลับมาด้วยวิธีเดียวกัน

ขั้นตอนมีดังนี้:

เชื่อมต่อ Git repo ของคุณและชี้ Apidog ไปยังไฟล์ spec
แก้ไข endpoint, สกีมา, และตัวอย่างในโปรแกรมแก้ไขภาพ
Apidog จะเขียน YAML ที่สะอาดและเปรียบเทียบง่ายกลับไปยังไฟล์
Commit บน branch และ push จากนั้นเปิด PR ของคุณตามปกติ

เนื่องจาก Apidog ทำให้ YAML เป็นลำดับอย่างสอดคล้องกัน การเปรียบเทียบของคุณจึงยังคงเล็กและตรวจสอบได้ ไม่มีการจัดเรียงใหม่หรือจัดรูปแบบใหม่ที่ก่อให้เกิดความรำคาญ คุณสามารถอ่านการตั้งค่าทั้งหมดได้ใน เอกสาร Apidog Spec-First Mode หากคุณต้องการให้ไฟล์อยู่ในผู้ให้บริการเฉพาะ ดู การซิงค์ OpenAPI spec ของคุณไปยัง GitHub

CI validation hooks

อย่าปล่อยให้ spec ที่ไม่ถูกต้องไปถึง main เชื่อมต่อการตรวจสอบความถูกต้องเข้ากับการตรวจสอบ pull-request ของคุณ เพื่อให้สัญญาที่เสียหายทำให้การ build ล้มเหลวโดยอัตโนมัติ

ขั้นตอน GitHub Actions ขั้นต่ำ:

name: Validate OpenAPI
on: [pull_request]
jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Lint spec
 run: npx @redocly/cli lint api/openapi.yaml

เพิ่มการตรวจสอบเพิ่มเติมเมื่อคุณเติบโต:

ตรวจสอบ spec สำหรับปัญหาโครงสร้างและสไตล์
ตรวจสอบว่าสามารถแยกวิเคราะห์เป็น OpenAPI 3.x ที่ถูกต้องตามกฎหมาย
เปรียบเทียบกับ main เพื่อตรวจจับการเปลี่ยนแปลงที่ส่งผลกระทบและติดธงบน PR

การตรวจสอบเหล่านี้ใช้เวลาไม่กี่วินาทีและตรวจจับข้อผิดพลาดที่ผู้ตรวจสอบที่เป็นมนุษย์อาจมองข้ามไป

แนวทางปฏิบัติที่ดีที่สุด

นิสัยบางอย่างช่วยให้การควบคุมเวอร์ชัน spec มีสุขภาพดีในระยะยาว:

ใช้การกำหนดเวอร์ชันเชิงความหมาย เพิ่มเวอร์ชัน info.version การเปลี่ยนแปลงที่ส่งผลกระทบหมายถึงเวอร์ชันหลักใหม่ การเพิ่มที่เข้ากันได้แบบย้อนหลังจะเพิ่มเวอร์ชันรอง
รักษา changelog ไฟล์ CHANGELOG.md สั้นๆ ถัดจาก spec จะบอกผู้บริโภคว่ามีการเปลี่ยนแปลงอะไประหว่างเวอร์ชัน
จัดส่งความแตกต่างเล็กๆ การเปลี่ยนแปลงเชิงตรรกะหนึ่งครั้งต่อ PR PR ของ spec ขนาดใหญ่ซ่อนการเปลี่ยนแปลงที่ส่งผลกระทบในความยุ่งเหยิง
เขียนข้อความ commit ที่สื่อความหมาย “เพิ่ม refundReason ในคำขอคืนเงิน” ดีกว่า “อัปเดต spec”
อย่าแก้ไข spec ที่รวมเข้ากับ main โดยตรง ไม่ว่าจะแก้ไขข้อผิดพลาดเล็กน้อยก็ควรแตก branch เสมอ

คำถามที่พบบ่อย

ฉันจะตรวจจับการเปลี่ยนแปลงที่ส่งผลกระทบใน OpenAPI spec ได้อย่างไร?

เรียกใช้เครื่องมือเปรียบเทียบ spec ใน CI ที่เปรียบเทียบ pull request กับเวอร์ชันบน main เครื่องมืออย่าง oasdiff จะจัดประเภทการเปลี่ยนแปลงแต่ละรายการว่าเป็น breaking (ส่งผลกระทบ), non-breaking (ไม่ส่งผลกระทบ), หรือ unclassified (ไม่จัดประเภท) และสามารถทำให้ build ล้มเหลวได้หากมีการเปลี่ยนแปลงที่ส่งผลกระทบ สิ่งนี้จะช่วยตรวจจับฟิลด์ที่ถูกลบ, พารามิเตอร์ที่จำเป็นใหม่, และประเภทที่เปลี่ยนแปลงซึ่งการตรวจสอบด้วยตนเองอาจพลาดไป

ฉันควรรักษาไฟล์ OpenAPI ไฟล์เดียว หรือแบ่งออกเป็นหลายไฟล์?

เริ่มต้นด้วยไฟล์ openapi.yaml ไฟล์เดียว การตรวจสอบและควบคุมเวอร์ชันทำได้ง่ายที่สุด เมื่อไฟล์มีขนาดใหญ่ขึ้นหรือคุณต้องดูแลเวอร์ชันหลักหลายเวอร์ชันพร้อมกัน ให้แบ่งตามเวอร์ชันหลัก (api-v1.yaml, api-v2.yaml) หรือใช้ $ref เพื่อแบ่งสกีมาออกเป็นไฟล์แยกกัน อย่าแบ่งก่อนเวลาอันควร ไฟล์ที่อ่านง่ายไฟล์เดียวย่อมดีกว่าไฟล์ที่กระจัดกระจายห้าไฟล์

ฉันสามารถควบคุมเวอร์ชัน spec ของฉันได้โดยไม่ต้องเขียน YAML ด้วยตนเองได้หรือไม่?

ได้ โหมด Spec-First ของ Apidog ช่วยให้คุณแก้ไข spec ในโปรแกรมแก้ไขภาพและซิงค์การเปลี่ยนแปลงไปยัง Git ได้ทั้งสองทิศทาง มันเขียน YAML ที่สอดคล้องกัน ดังนั้นการเปรียบเทียบของคุณจึงยังคงสะอาดและ pull request ของคุณยังคงอ่านง่าย ในขณะที่คุณยังคงได้รับประวัติ Git และการตรวจสอบอย่างเต็มที่

button