API Spec คืออะไร: ทำไมต้องดูแลเหมือนโค้ด

สัญญา API ของคุณอาจอยู่ในหลายที่พร้อมกันถึงสามแห่ง แผนภาพในวิกิ, คอลเลกชัน Postman ที่มีคนส่งออกเมื่อไตรมาสที่แล้ว, หรือเอกสาร Markdown ที่เขียนด้วยมือซึ่งเนื้อหาแตกต่างจากบริการที่ใช้งานจริงเมื่อสองรุ่นก่อน เมื่อทั้งสามสิ่งนี้ไม่ตรงกัน ทีมของคุณก็จะเดาสุ่ม การเดาสุ่มทำให้การเชื่อมต่อใช้งานไม่ได้

การจัดการข้อกำหนด API ของคุณให้เป็นโค้ดจะช่วยแก้ไขปัญหานี้ได้ คุณเขียนไฟล์ OpenAPI เพียงไฟล์เดียว, คอมมิตเข้าสู่ Git, และตรวจสอบเหมือนกับไฟล์ซอร์สโค้ดอื่นๆ จากไฟล์เดียวนี้ คุณสามารถสร้าง mocks, tests, docs, และ SDKs ได้ ข้อกำหนดจะไม่ใช่สิ่งที่คุณเพิ่งนึกถึงทีหลังอีกต่อไป แต่จะกลายเป็นสัญญาหลักที่ทุกคนใช้เป็นพื้นฐานในการพัฒนา

คู่มือนี้จะอธิบายว่า spec-as-code หมายถึงอะไร, ทำไมไฟล์ OpenAPI จึงสมควรได้รับการพิจารณาอย่างละเอียดถี่ถ้วนเช่นเดียวกับโค้ดแอปพลิเคชันของคุณ, และวิธีดำเนินการเวิร์กโฟลว์โดยไม่ต้องต่อสู้กับเครื่องมือของคุณ

Spec-as-code หมายถึงอะไร

Spec-as-code หมายถึงคำจำกัดความ API ของคุณเป็นไฟล์ข้อความธรรมดาที่อยู่ภายใต้ระบบควบคุมเวอร์ชัน ไม่ใช่ข้อมูลในฐานข้อมูล ไม่ใช่เอกสารที่โฮสต์พร้อมลิงก์สำหรับแชร์ เป็นไฟล์ที่คุณสามารถ git diff, แยกสาขา (branch) และรวม (merge) ได้

แนวคิดนี้มาจาก docs-as-code โดยตรง ที่ซึ่งเอกสารประกอบจะอยู่ในพื้นที่เก็บข้อมูล (repo) เดียวกันกับโค้ดที่อธิบาย และถูกนำส่งผ่านไปป์ไลน์เดียวกัน Spec-as-code ใช้หลักการเดียวกันกับสัญญา API เอง เอกสาร OpenAPI (YAML หรือ JSON) คือผลผลิตหลัก (artifact) ส่วนประกอบอื่น ๆ ที่ตามมาจะถูกสร้างขึ้นจากมัน

การเปลี่ยนแปลงนี้มีผลลัพธ์สำคัญอย่างหนึ่ง ข้อกำหนดกลายเป็นแหล่งความจริงเพียงแหล่งเดียว เมื่อนักพัฒนาต้องการทราบว่า /users/{id} ส่งคืนอะไร พวกเขาจะอ่านข้อกำหนด ไม่ใช่หน้าวิกิที่ล้าสมัย เมื่อ QA เขียนการทดสอบ พวกเขาจะยืนยันกับข้อกำหนด เมื่อพาร์ทเนอร์ทำการเชื่อมต่อ พวกเขาจะดึง SDK ที่สร้างจากข้อกำหนด หนึ่งไฟล์ หลายผลลัพธ์

ทำไมต้องจัดการข้อกำหนดเหมือนโค้ด

เมื่อข้อกำหนดเป็นไฟล์ใน Git แล้ว คุณจะได้รับเวิร์กโฟลว์ทั้งหมดที่คุณเชื่อถือสำหรับซอร์สโค้ด

การตรวจสอบในพูลรีเควสต์ การเปลี่ยนแปลงของเอนด์พอยต์จะแสดงเป็นส่วนต่าง (diff) ใน PR ผู้ตรวจสอบจะเห็นได้อย่างชัดเจนว่าฟิลด์ใดบ้างที่เปลี่ยนแปลงไป, รหัสสถานะใดที่ถูกเพิ่มเข้ามา, และรูปแบบการตอบกลับทำให้เกิดความไม่เข้ากันย้อนหลัง (backward compatibility) หรือไม่ การเปลี่ยนแปลงที่ส่งผลกระทบจะไม่ใช่เรื่องน่าประหลาดใจในเวอร์ชันที่ใช้งานจริงอีกต่อไป มันคือกระทู้ความคิดเห็นก่อนการรวมโค้ด นี่คือหัวใจสำคัญของ เวิร์กโฟลว์ API ที่ทำงานร่วมกับ Git

รูปแบบที่ง่ายต่อการเปรียบเทียบความแตกต่าง (Diff-friendly) ไฟล์ YAML ทั่วไปสามารถเปรียบเทียบความแตกต่างได้อย่างชัดเจน คุณสามารถอ่านการเปลี่ยนแปลงห้าบรรทัดและเข้าใจได้ในไม่กี่วินาที เปรียบเทียบกับการส่งออกไบนารีหรือเครื่องมือที่โฮสต์ซึ่ง “สิ่งที่เปลี่ยนแปลง” นั้นมองไม่เห็น เมื่อข้อกำหนดอยู่ใน Git การระบุผู้กระทำ (blame), ประวัติ และการเปรียบเทียบความแตกต่าง (diffs) ก็จะทำงานได้ทั้งหมด

การควบคุมเวอร์ชันจริง ทุกการเปลี่ยนแปลงมีคอมมิต, ผู้เขียน และการประทับเวลา คุณสามารถแท็กเวอร์ชัน (tag a release), สร้างสาขา (branch) สำหรับการออกแบบ v2 ใหม่, และย้อนกลับการเปลี่ยนแปลงที่ไม่ถูกต้องด้วยคำสั่งเดียว ประวัติ API ของคุณสามารถตรวจสอบได้ สำหรับข้อมูลเชิงลึกเพิ่มเติมเกี่ยวกับกลยุทธ์การแท็กและการสร้างสาขา โปรดดูที่ การควบคุมเวอร์ชัน OpenAPI ด้วย Git

แหล่งความจริงเพียงแหล่งเดียว เนื่องจาก mocks, tests และ docs ทั้งหมดมาจากไฟล์เดียวกัน จึงไม่สามารถคลาดเคลื่อนออกจากกันได้ อัปเดตข้อกำหนด, สร้างใหม่ และผลลัพธ์ทั้งหมดจะยังคงสอดคล้องกัน

นี่คือการเปรียบเทียบวิธีการสองแบบในการปฏิบัติจริง

OpenAPI ในฐานะผลผลิตหลัก (Artifact)

OpenAPI เป็นรูปแบบที่ชัดเจนสำหรับข้อกำหนด เนื่องจากได้รับการสนับสนุนอย่างกว้างขวางและเครื่องอ่านได้ นี่คือส่วนเล็กๆ แต่สมบูรณ์ของไฟล์ OpenAPI 3.1 ที่คุณจะเก็บไว้ใน repo ของคุณ

openapi: 3.1.0
info:
 title: Orders API
 version: 1.2.0
paths:
 /orders/{orderId}:
 get:
 summary: Get an order by ID
 operationId: getOrder
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 format: uuid
 responses:
 "200":
 description: The requested order
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"
 "404":
 description: Order not found
components:
 schemas:
 Order:
 type: object
 required: [id, status, total]
 properties:
 id:
 type: string
 format: uuid
 status:
 type: string
 enum: [pending, shipped, delivered]
 total:
 type: number
 format: float

ไฟล์นี้คือสัญญา เพิ่มฟิลด์ลงใน Order และความแตกต่างก็คือหนึ่งบรรทัด เปลี่ยน enum ของ status และผู้ตรวจสอบจะเห็นได้ทันที เก็บไว้ใต้ api/openapi.yaml ถัดจากโค้ดบริการของคุณ และข้อกำหนดจะเดินทางไปพร้อมกับการนำไปใช้งานที่อธิบายไว้

ข้อกำหนดและเอกสาร

ผลตอบแทนจากการมีไฟล์ต้นฉบับเดียวคือทุกสิ่งที่ถูกสร้างขึ้นจากมัน

Mocks (จำลอง) ชี้เซิร์ฟเวอร์จำลองไปยังข้อกำหนด และคุณจะได้ API ที่ทำงานได้ก่อนที่จะมีการสร้างเอนด์พอยต์แม้แต่ตัวเดียว ทีมฟรอนต์เอนด์และโมบายล์เริ่มเชื่อมต่อกับสัญญาตั้งแต่วันแรก เมื่อข้อกำหนดเปลี่ยน mock ก็จะเปลี่ยนตามไปด้วย

การทดสอบ สร้างการทดสอบสัญญาที่ยืนยันว่าบริการที่ใช้งานจริงตรงกับข้อกำหนด หากเอนด์พอยต์ที่นำไปใช้งานส่งคืนฟิลด์ที่ข้อกำหนดไม่เคยประกาศไว้ การทดสอบจะล้มเหลว สิ่งนี้ช่วยตรวจจับความคลาดเคลื่อนระหว่างสัญญาและโค้ดที่ทำงานอยู่ ก่อนที่ลูกค้าจะพบ

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

SDKs สร้างไลบรารีไคลเอ็นต์ในหลายภาษาจากไฟล์เดียวกัน พาร์ทเนอร์จะได้รับ typed SDK ที่สะท้อนสัญญาปัจจุบันอยู่เสมอ

แต่ละผลลัพธ์เป็นฟังก์ชันของข้อกำหนด เปลี่ยนอินพุต, สร้างผลลัพธ์ใหม่ และความสอดคล้องกันจะเกิดขึ้นโดยอัตโนมัติ

Apidog ทำให้ข้อกำหนดเป็นแหล่งความจริงเพียงแหล่งเดียวได้อย่างไร

การใช้งาน spec-as-code ด้วยตนเองหมายถึงการนำ CLI, เซิร์ฟเวอร์จำลอง, ตัวสร้างเอกสาร และ Git hook มาประกอบเข้าด้วยกัน Apidog รวมสิ่งเหล่านั้นเข้าไว้ในเวิร์กโฟลว์เดียว

โหมด Spec-First ของ Apidog ถือว่าไฟล์ OpenAPI ของคุณเป็นคำจำกัดความที่เชื่อถือได้ คุณออกแบบเอนด์พอยต์โดยอิงจากข้อกำหนด และ Apidog จะทำให้ mocks, tests และเอกสารของคุณสอดคล้องกันไปพร้อมกับข้อกำหนดนั้น

ส่วนที่ทำให้สิ่งนี้เป็นไปได้จริงคือการซิงค์ Git แบบสองทาง Apidog สามารถอ่านไฟล์ OpenAPI ของคุณจาก repo และเขียนการเปลี่ยนแปลงกลับเข้าไปได้ ทำให้ไฟล์ใน Git และโปรเจกต์ใน Apidog มีความสอดคล้องกัน ออกแบบด้วยภาพเมื่อทำได้เร็วกว่า, แก้ไข YAML โดยตรงเมื่อทำได้เร็วกว่า, และทั้งสองวิธีจะนำไปสู่ไฟล์ที่คอมมิตเดียวกัน ซึ่งจะช่วยรักษากระบวนการตรวจสอบ PR ของคุณให้สมบูรณ์ ในขณะเดียวกันก็มอบเครื่องมือแก้ไขที่สมบูรณ์ยิ่งขึ้นให้กับทีมของคุณ สำหรับกลไกการพุชการเปลี่ยนแปลงข้อกำหนดไปยังส่วนต้นทาง (upstream) โปรดดู วิธีการซิงค์ OpenAPI spec ของคุณไปยัง GitHub

ผลลัพธ์: ไฟล์ OpenAPI ยังคงเป็นแหล่งความจริงเพียงแหล่งเดียว และเครื่องมือสร้างภาพจะอยู่บนไฟล์นั้น แทนที่จะเข้ามาแทนที่

ข้อผิดพลาดที่พบบ่อย

Spec-as-code นั้นตรงไปตรงมา แต่มีข้อผิดพลาดบางอย่างที่ทีมมักจะเจอในช่วงแรก

ความคลาดเคลื่อนระหว่างข้อกำหนดกับการนำไปใช้งาน การเขียนข้อกำหนดอย่างเดียวไม่เพียงพอ หากไม่มีสิ่งใดตรวจสอบว่าบริการที่ทำงานอยู่ตรงกับข้อกำหนด ทั้งสองก็จะค่อยๆ คลาดเคลื่อนจากกันไปเงียบๆ เพิ่มการทดสอบสัญญา (contract tests) เข้าไปใน CI เพื่อให้ความไม่ตรงกันทำให้บิลด์ล้มเหลว ไม่ใช่ลูกค้า

ความสับสนระหว่างสิ่งที่สร้างขึ้นอัตโนมัติกับสิ่งที่เขียนด้วยมือ ตัดสินใจว่าข้อกำหนดถูกสร้างขึ้นจากคำอธิบายประกอบโค้ด (code annotations) หรือเขียนด้วยมือเป็นแหล่งที่มาหลัก การผสมผสานทั้งสองอย่างทำให้เกิดไฟล์ที่ไม่มีใครรู้ว่าส่วนใดเป็นส่วนที่เชื่อถือได้ เลือกไปทางใดทางหนึ่ง หากข้อกำหนดเป็นแหล่งความจริงของคุณ ให้ถือว่าคำอธิบายประกอบโค้ดเป็นสิ่งที่คุณใช้ตรวจสอบกับข้อกำหนดนั้น ไม่ใช่สำเนาหลักที่สอง

การถือว่าข้อกำหนดเป็นเพียงเอกสารประกอบ ไม่ใช่สัญญา ข้อกำหนดที่คุณเพียงแค่อ่านคือเอกสาร ข้อกำหนดที่คุณใช้สร้าง mocks, tests และ SDKs คือสัญญา คุณค่ามาจากการเชื่อมต่อผลลัพธ์ ไม่ใช่จากการมีอยู่ของไฟล์

การข้ามการตรวจสอบ ข้อกำหนดใน Git ที่รวมเข้าด้วยกันโดยไม่มีการตรวจสอบก็เป็นเพียงไฟล์หนึ่งใน Git เท่านั้น ประเด็นสำคัญคือพูลรีเควสต์ กำหนดให้มีการตรวจสอบการเปลี่ยนแปลงข้อกำหนดในลักษณะเดียวกับการตรวจสอบโค้ด

เริ่มต้นใช้งาน

คุณสามารถนำ spec-as-code มาปรับใช้ได้ทีละน้อย

1. คอมมิตข้อกำหนดของคุณ ย้ายไฟล์ OpenAPI ของคุณเข้าไปใน repo ที่พาธที่กำหนด เช่น api/openapi.yaml
2. กำหนดให้มีการตรวจสอบ PR ทำให้การเปลี่ยนแปลงข้อกำหนดต้องผ่านกระบวนการตรวจสอบเช่นเดียวกับโค้ด ความแตกต่าง (Diffs) จะกลายเป็นหัวข้อสนทนา
3. สร้างผลลัพธ์หนึ่งอย่าง เริ่มต้นด้วย mocks หรือ docs เชื่อมต่อข้อกำหนดเข้ากับตัวสร้างเพื่อให้ผลลัพธ์อัปเดตเมื่อไฟล์มีการเปลี่ยนแปลง
4. เพิ่มการตรวจสอบ CI ตรวจสอบข้อกำหนด (Lint the spec) ในทุก PR ตรวจจับ OpenAPI ที่ไม่ถูกต้องก่อนการรวมโค้ด
5. ปิดวงจรด้วยการทดสอบสัญญา เมื่อ mocks และ docs ทำงานได้แล้ว ให้เพิ่มการทดสอบที่ยืนยันว่าบริการที่ใช้งานจริงตรงกับข้อกำหนด

แต่ละขั้นตอนมีความสมบูรณ์ในตัวเอง คุณจะได้รับประโยชน์ตั้งแต่ขั้นตอนแรก และจะเพิ่มขึ้นเรื่อยๆ ในแต่ละส่วนที่เพิ่มเข้ามา

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

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

“API spec as code” เหมือนกับ “docs-as-code” หรือไม่?

ทั้งสองมีปรัชญาเดียวกัน: เก็บผลผลิตหลัก (artifact) ไว้ในการควบคุมเวอร์ชันและจัดส่งผ่านไปป์ไลน์ปกติของคุณ Docs-as-code นำไปใช้กับเอกสารประกอบ Spec-as-code นำไปใช้กับสัญญา API เอง ในทางปฏิบัติ ทั้งสองเสริมซึ่งกันและกัน เนื่องจากเอกสารที่สร้างจากข้อกำหนดที่คอมมิตถือเป็น docs-as-code โดยนิยาม

ไฟล์ข้อกำหนดควรใช้รูปแบบใด?

OpenAPI ในรูปแบบ YAML เป็นตัวเลือกที่นิยม YAML สามารถเปรียบเทียบความแตกต่าง (diffs) ได้อย่างชัดเจนในพูลรีเควสต์และมนุษย์สามารถอ่านได้ ในขณะที่ยังคงสามารถแยกวิเคราะห์โดยเครื่องจักรเพื่อสร้าง mocks, tests และ SDKs JSON ก็ใช้ได้เช่นกัน แต่ YAML มักจะสร้างความแตกต่างที่เรียบร้อยกว่า

ฉันจะป้องกันไม่ให้ข้อกำหนดคลาดเคลื่อนจาก API จริงได้อย่างไร?

เพิ่มการทดสอบสัญญา (contract tests) เข้าไปใน CI ที่ยืนยันว่าบริการที่ทำงานอยู่ตรงกับข้อกำหนดที่คอมมิตไว้ หากเอนด์พอยต์ส่งคืนฟิลด์ที่ไม่ได้ประกาศไว้ หรือละทิ้งฟิลด์ที่มีการบันทึกไว้ บิลด์จะล้มเหลว วงจรการตอบรับนี้คือสิ่งที่เปลี่ยนข้อกำหนดจากเอกสารที่คาดหวังให้เป็นสัญญาที่บังคับใช้ได้