Apidog เลือกโหมดไหนดี Spec-First หรือ Design-First

โมดูล API ของ Apidog ให้คุณสร้างสิ่งเดียวกันได้สองวิธี: สัญญา API วิธีหนึ่งใช้ฟอร์มแบบภาพ อีกวิธีหนึ่งใช้ตัวแก้ไขโค้ดดิบที่เชื่อมต่อกับ Git ทั้งสองวิธีสร้าง OpenAPI ที่ถูกต้อง ความแตกต่างอยู่ที่วิธีการทำงานประจำวันของทีมคุณ และวิธีใดที่เหมาะสมนั้นขึ้นอยู่กับนิสัยของคุณมากกว่าเครื่องมือ

คู่มือนี้จะอธิบายการตัดสินใจระหว่าง design-first และ spec-first ใน Apidog: แต่ละโหมดคืออะไร, จัดการ Git อย่างไร, และทีมใดมักจะเลือกวิธีใด คุณสามารถสลับระหว่างโหมดเหล่านี้ได้จากปุ่มสลับเดียวที่มุมล่างซ้ายของโมดูล API ดังนั้นทางเลือกนี้จึงไม่ถาวร แต่การเลือกค่าเริ่มต้นที่ถูกต้องจะช่วยลดความยุ่งยากได้

ปุ่ม

สองปรัชญา

ก่อนที่จะพูดถึงโหมดต่างๆ มาพูดถึงแนวคิดกันก่อน ทั้งสองวิธีมีกฎเดียวกัน: คุณกำหนดสัญญา API ก่อนที่จะเขียนการใช้งาน สัญญาคือแหล่งที่มาของความจริง โค้ด, การทดสอบ, การจำลอง (mocks) และเอกสารทั้งหมดล้วนมาจากสัญญา

Design-first หมายถึงคุณกำหนดรูปร่างสัญญาผ่านอินเทอร์เฟซที่มีโครงสร้าง คุณเพิ่มเอนด์พอยต์, พารามิเตอร์, และสคีมาผ่านฟอร์มและเมนูดร็อปดาวน์ เครื่องมือจะรับประกันว่าผลลัพธ์ถูกต้อง เพราะคุณสามารถป้อนค่าที่ถูกต้องเท่านั้น

Spec-first (มักเรียกว่า contract-first) หมายถึงคุณเขียนสัญญาโดยตรงในรูปแบบไฟล์ข้อกำหนด: OpenAPI ใน YAML หรือ JSON ข้อกำหนด คือ พื้นที่ทำงานของคุณ คุณแก้ไขมันเหมือนซอร์สโค้ด

ในทางปฏิบัติ ศัพท์เหล่านี้ทับซ้อนกัน "Contract-first" และ "spec-first" เกือบจะเป็นคำพ้องความหมาย และหลายทีมใช้ "design-first" อย่างหลวมๆ เพื่อหมายถึงวิธีการใดๆ ที่สัญญาอยู่ก่อนโค้ด ความแตกต่างที่มีประโยชน์ในที่นี้เป็นรูปธรรม: ใน Apidog โหมดหนึ่งให้คุณใช้ฟอร์ม อีกโหมดหนึ่งให้คุณใช้ตัวแก้ไขข้อความ นั่นคือเส้นแบ่งที่สำคัญเมื่อคุณกำลังเลือก

ควรแยกทั้งสองออกจาก design-first กับ code-first ในการพัฒนา API Code-first สร้างข้อกำหนด จาก แอนโนเทชันในการใช้งานของคุณ ดังนั้นโค้ดจึงเป็นตัวนำ โหมดทั้งสองของ Apidog เก็บสัญญาไว้หน้าโค้ด เพียงแต่พวกมันไม่เห็นด้วยกับวิธีการเขียน สำหรับภาพรวมที่กว้างขึ้นของการปฏิบัติต่อข้อกำหนดของคุณในฐานะสิ่งประดิษฐ์ที่มีเวอร์ชัน โปรดดูภาพรวมของเราเกี่ยวกับ เวิร์กโฟลว์ API ที่ใช้ Git เป็นหลัก

โหมด Apidog Design-First

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

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

Design-First Mode ยังรองรับ branches ทำให้ทีมสามารถทำงานในเวอร์ชันแยกต่างหากของการออกแบบ API พร้อมกันและแก้ไขความขัดแย้งในภายหลัง ผู้ตรวจสอบจะเห็นความแตกต่างที่มีโครงสร้างแทนที่จะเป็นข้อความดิบ ทำให้การเปลี่ยนแปลงสัญญาอ่านง่ายขึ้นสำหรับผู้ที่ไม่ได้คุ้นเคยกับ YAML

ข้อเสีย: คุณกำลังทำงานผ่านนามธรรม หากคุณคิดในรูปแบบ OpenAPI อยู่แล้ว ฟอร์มอาจรู้สึกเหมือนเป็นขั้นตอนพิเศษระหว่างคุณกับสเปกที่คุณมีอยู่ในหัว

โหมด Apidog Spec-First

Spec-First Mode ซึ่งขณะนี้อยู่ในช่วงเบต้า จะสลับแนวคิดนั้น แทนที่จะใช้ฟอร์ม คุณจะได้รับตัวแก้ไขโค้ดสไตล์ IDE และคุณเขียน OpenAPI หรือ Swagger spec โดยตรงใน YAML หรือ JSON มันถูกสร้างขึ้นสำหรับทีมที่ต้องการให้คำจำกัดความ API ของพวกเขาอยู่ใน Git เหมือนกับไฟล์ซอร์สอื่น ๆ

ตัวแก้ไขทำงานเหมือนกับตัวแก้ไขในโค้ดของคุณ: การเน้นไวยากรณ์ (syntax highlighting), การตรวจสอบความถูกต้องแบบอินไลน์ (inline validation), และการเติมข้อความอัตโนมัติ (auto-completion) ที่ปรับแต่งมาสำหรับ OpenAPI และ Swagger schemas ขณะที่คุณพิมพ์ แถบด้านซ้ายจะแยกวิเคราะห์สเปกของคุณโดยอัตโนมัติเป็นโครงร่างของพาธและส่วนประกอบต่างๆ เพื่อให้คุณสามารถนำทางไฟล์ขนาดใหญ่ได้โดยไม่ต้องเลื่อน ตัวบ่งชี้การซิงค์จะแสดงว่าการแก้ไขในเครื่องของคุณสอดคล้องกับ repository ที่เชื่อมต่ออยู่หรือไม่

จุดเด่นคือการซิงค์ Git แบบสองทาง คุณเชื่อมต่อ repository บน GitHub หรือ GitLab (Azure DevOps ทำงานผ่าน Git Connection ทั่วไป) และ Apidog จะซิงค์ไฟล์ spec ของคุณทั้งสองทิศทาง แก้ไขใน Apidog จากนั้น commit และ push ตรงจากแอป หรือแก้ไข spec ในตัวแก้ไขโค้ดของคุณ push จากที่นั่น และดึงการเปลี่ยนแปลงกลับมายัง Apidog ไฟล์ spec คือความจริงที่ใช้ร่วมกัน และทั้งสองส่วนจะสอดคล้องกัน คุณสามารถอ่านการตั้งค่าทั้งหมดได้ใน เอกสาร Spec-First Mode

โหมดนี้ปฏิบัติต่อสัญญา API ของคุณเหมือนกับที่คุณจะปฏิบัติต่อสิ่งประดิษฐ์โค้ดอื่นๆ: ตรวจสอบในการร้องขอแบบดึง (pull requests), จัดเวอร์ชันควบคู่ไปกับบริการที่ใช้งาน, และเปรียบเทียบทีละบรรทัด หากทีมของคุณจัดการโครงสร้างพื้นฐานและการกำหนดค่าแบบนี้อยู่แล้ว โปรดดูข้อมูลเชิงลึกของเราเกี่ยวกับ API spec as code สำหรับเหตุผลเบื้องหลัง

การเปรียบเทียบแบบเคียงข้างกัน

ทั้งสองโหมดสร้าง OpenAPI เดียวกันและรองรับการจำลอง (mocking), การทดสอบ (testing), และเอกสารประกอบ (docs) ในขั้นตอนถัดไป พวกมันแตกต่างกันในวิธีการเขียนและจัดเวอร์ชันของสเปก

ทีมใดควรเลือกวิธีใด

ใช้ Design-First Mode หากผู้มีส่วนร่วมของคุณไม่ใช่ผู้เชี่ยวชาญ OpenAPI ทั้งหมด ผู้จัดการผลิตภัณฑ์, QA, และวิศวกรฝึกหัดทุกคนสามารถเพิ่มหรือตรวจสอบเอนด์พอยต์ได้โดยไม่ต้องเรียนรู้ไวยากรณ์ของสเปก นอกจากนี้ยังเป็นเส้นทางที่เร็วกว่าเมื่อคุณเริ่มต้น API ใหม่ตั้งแต่ต้น และต้องการดำเนินการผ่านโครงสร้างอย่างรวดเร็วโดยไม่ต้องกังวลเรื่องการจัดรูปแบบ

ใช้ Spec-First Mode หากสเปกของคุณมีอยู่แล้ว หรือควรจะอยู่ใน Git repository ถัดจากโค้ดบริการของคุณ ทีมแบ็กเอนด์ที่ตรวจสอบการเปลี่ยนแปลง API ใน pull requests, รัน spec linting ใน CI, หรือต้องการไฟล์ YAML มาตรฐานเดียวที่ใช้ได้กับเครื่องมือต่างๆ จะรู้สึกคุ้นเคย การซิงค์สองทางหมายความว่า Apidog จะไม่เป็นสำเนาของความจริงที่แยกต่างหากอีกต่อไป แต่จะกลายเป็นหน้าต่างที่มองเห็นไฟล์เดียวกันกับที่ repo ของคุณเก็บไว้

เส้นทางสายกลางที่ใช้งานได้จริง: หลายทีมออกแบบเอนด์พอยต์ใหม่ใน Design-First Mode เพื่อความรวดเร็ว จากนั้นย้ายไป Spec-First เมื่อ API มีความสมบูรณ์และ Git review กลายเป็นสิ่งสำคัญ โหมดเหล่านี้ไม่ใช่ผลิตภัณฑ์คู่แข่งกัน พวกมันเป็นสองมุมมองของสัญญาฉบับเดียวกัน

วิธีการสลับโหมด

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

ข้อควรจำบางประการเมื่อคุณสลับ:

• สเปกที่อยู่เบื้องหลังถูกใช้ร่วมกัน ดังนั้นเอนด์พอยต์, สคีมา, และตัวอย่างของคุณจะถูกนำไปใช้ทั้งหมด คุณกำลังเปลี่ยนพื้นผิวการแก้ไข ไม่ใช่การสร้าง API ใหม่
• ในการใช้ Git sync ของ Spec-First Mode ให้เชื่อมต่อ repository GitHub, GitLab, หรือ Azure DevOps ของคุณก่อน เมื่อเชื่อมต่อแล้ว ตัวบ่งชี้การซิงค์จะบอกคุณว่าการแก้ไขของคุณได้ถูก commit และ push แล้วหรือไม่
• เนื่องจาก Spec-First Mode อยู่ในช่วงเบต้า ลองใช้กับโปรเจกต์ที่คุณสามารถยืนยันพฤติกรรมการซิงค์ได้ก่อนที่จะพึ่งพามันสำหรับสัญญาในการผลิต

คุณสามารถย้ายไปมาได้เมื่อความต้องการของคุณเปลี่ยนไป ดังนั้นถือว่าการเลือกนี้เป็นค่าเริ่มต้นมากกว่าข้อผูกมัด

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

Spec-first เหมือนกับ contract-first หรือไม่?

ในทางปฏิบัติแล้วใช่ "Spec-first" และ "contract-first" ทั้งสองหมายถึงการที่คุณเขียนข้อกำหนด API ก่อนที่จะนำไปใช้งาน และทั้งสองถือว่าข้อกำหนดนั้นเป็นแหล่งที่มาของความจริง Spec-First Mode ของ Apidog เป็นเวิร์กโฟลว์แบบ contract-first โดยที่สัญญาคือไฟล์ OpenAPI หรือ Swagger ที่เขียนด้วยมือและซิงค์กับ Git

Spec-First Mode ทำงานร่วมกับ GitLab และ Azure DevOps ได้หรือไม่?

ได้ Spec-First Mode รองรับการซิงค์ Git แบบสองทางกับ GitHub และ GitLab โดยตรง Azure DevOps ทำงานผ่าน Generic Git Connection คุณจึงสามารถซิงค์ไฟล์ spec ของคุณไปยัง repository ที่โฮสต์บน Azure ได้เช่นกัน

ฉันสามารถสลับจาก design-first ไป spec-first โดยไม่เสียงานได้หรือไม่?

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

ไม่แน่ใจว่าแบบใดเหมาะสมกับทีมของคุณ? เปิดโมดูล APIs ลองสลับโหมดที่มุมล่างซ้าย และออกแบบเอนด์พอยต์ถัดไปของคุณทั้งสองวิธี สัญญาจะเหมือนกันไม่ว่าจะใช้วิธีใด; เลือกพื้นผิวที่ตรงกับวิธีการทำงานของทีมคุณ

ปุ่ม