มีสองกลุ่มในทุกทีม API ที่ผมเคยทำงานด้วย
กลุ่มหนึ่งเขียน OpenAPI spec ด้วยมือ แล้วคอมมิตลงในไดเรกทอรี `specs/` และถือว่า Git เป็นแหล่งความจริง อีกกลุ่มหนึ่งคลิกผ่านเครื่องมือออกแบบภาพ แล้วส่งออก spec เมื่อ CI แจ้งเตือน และแก้ไขความคลาดเคลื่อนที่เกิดขึ้นระหว่างสองรูปแบบนับตั้งแต่เมื่อวันอังคารที่แล้ว
ผมเคยอยู่ทั้งสองกลุ่ม กลุ่มแรกจะช้ากว่าในวันแรกและเร็วกว่าในวันที่เก้าสิบ ส่วนกลุ่มที่สองจะตรงกันข้าม และจนกระทั่งประมาณหนึ่งเดือนที่แล้ว เครื่องมือออกแบบ API ที่ผมใช้บ่อยที่สุด — Apidog — รองรับแต่กลุ่มที่สองเท่านั้น เครื่องมือออกแบบภาพของมันยอดเยี่ยมมาก แต่การส่งผ่าน YAML ไปกลับเป็นคุณสมบัติที่คุณต้องพยายามปกป้องในการตรวจสอบโค้ด
จากนั้นในช่วงกลางเดือนเมษายน Spec-First Mode (Beta) ได้ปรากฏขึ้นในกล่องโต้ตอบ New Project ผมจงใจไม่ได้เขียนถึงเรื่องนี้ในวันเปิดตัว ผมต้องการใช้งานมันกับโปรเจกต์จริงก่อน และต้องการรอให้นานพอที่ข้อบกพร่องในช่วงต้นสัปดาห์จะได้มีโอกาสปรากฏขึ้น หนึ่งเดือนเป็นเวลาที่เหมาะสม โพสต์นี้คือสิ่งที่ผมพบหลังจากใช้เวลาช่วงเช้ากับเวอร์ชันเบต้าเทียบกับ OpenAPI spec จากโปรเจกต์ส่วนตัวของผม — สิ่งที่ผมจะบอกเพื่อนร่วมทีมก่อนที่พวกเขาจะลองใช้ และข้อดีข้อเสียของมัน
Spec-First Mode เปลี่ยนแปลงอะไรไปบ้าง
สรุปสั้นๆ: Apidog ตอนนี้มีสองโหมดโปรเจกต์ และมันเป็นผลิตภัณฑ์ที่แตกต่างกันอย่างแท้จริง
โหมดเริ่มต้นคือสิ่งที่คนส่วนใหญ่รู้จัก คุณคลิก + New Project คุณจะได้รับโครงสร้างโฟลเดอร์และแบบฟอร์มภาพ และคุณสร้าง endpoint โดยการกรอกข้อมูลในช่องต่างๆ OpenAPI spec จะถูกสร้างขึ้นเบื้องหลัง มันทำงานได้ดี โดยเฉพาะอย่างยิ่งสำหรับทีมที่ยังไม่มีความคุ้นเคยกับการใช้ YAML
Spec-First Mode แทนที่โปรแกรมแก้ไขแบบฟอร์มด้วยโปรแกรมแก้ไขโค้ดจริงสำหรับไฟล์ `.yaml` และ `.json` ดิบๆ พร้อมกับการซิงค์แบบสองทางกับที่เก็บ Git ของคุณ OpenAPI spec ของคุณคือไฟล์บนดิสก์ ไม่ใช่การแปลงข้อมูลจากการคลิก มีการเน้นไวยากรณ์ การเติมข้อความอัตโนมัติที่สอดคล้องกับ OpenAPI schema และช่อง "Real-time Directory Parsing" ที่สร้างโครงร่าง endpoint ในแถบด้านข้างจากโค้ดของคุณในขณะที่คุณพิมพ์
รายละเอียดสุดท้ายคือสิ่งที่ผมจะนำเสนอถ้าผมต้องสาธิตให้ผู้สงสัยฟัง เหตุผลที่เครื่องมือออกแบบภาพมีอยู่ไม่ใช่เพราะ YAML ยาก — แต่เป็นเพราะ YAML ซ่อนโครงสร้างไว้จนกว่าคุณจะเลื่อนผ่านไปแล้ว มุมมองโครงร่างของ Apidog แก้ปัญหานั้นได้โดยไม่ต้องให้คุณละทิ้งไฟล์ คุณเขียน spec คุณก็ได้การนำทาง ทั้งสองสิ่งอยู่ร่วมกันบนหน้าจอ
ข้อสรุป หากมี: การพัฒนาแบบ spec-first ไม่ใช่เรื่องของการเลือกใช้โปรแกรมแก้ไขข้อความ แต่มันเป็นเรื่องที่ว่าใครเป็นเจ้าของ artifact Spec-First Mode ทำให้ artifact เป็นไฟล์ในที่เก็บของคุณ จบ. UI เป็นเพียงหน้าต่างที่มองเข้าไป ไม่ใช่แค่การห่อหุ้มมันไว้
การตั้งค่าตั้งแต่ต้นจนจบ
นี่คือขั้นตอนที่ผมทำ ใช้เวลาน้อยกว่าสิบนาที ซึ่งส่วนใหญ่เป็นการอนุญาต Git
1. สร้างโปรเจกต์ในโหมดที่ถูกต้อง จากหน้าจอโปรเจกต์, + New Project → General → Spec-first Mode ตัวเลือกโหมดนี้อาจถูกมองข้ามได้ง่ายหากคุณสร้างโปรเจกต์โดยอัตโนมัติมาเป็นปี — General Mode มีป้าย "แนะนำ" และสายตาของคุณอาจเลื่อนผ่านช่องที่สองไปเลย ชะลอความเร็วตรงนี้
2. เชื่อมต่อกับที่เก็บ Git ของคุณ เลื่อนไปที่ Connect with Git Repository และอนุญาตผู้ให้บริการของคุณ ผมใช้ GitHub; เอกสารครอบคลุมถึงผู้ให้บริการอื่นๆ จากนั้นเลือก Organization, Repository, และ Main branch Apidog จะซิงค์ไฟล์ spec ในสาขานั้นเป็นสำเนาที่คุณทำงาน
3. กำหนดค่าโปรเจกต์ ป้อน Project Name, ตั้งค่าสิทธิ์ของทีม, และ Create การซิงค์ครั้งแรกจะดึงไฟล์ `.yaml` และ `.json` ทั้งหมดที่อยู่ในที่เก็บเข้าสู่พื้นที่ทำงานของ Apidog
4. แก้ไข spec เหมือนไฟล์ ไม่ใช่แบบฟอร์ม เปิดไฟล์ YAML ไฟล์ใดไฟล์หนึ่ง คุณจะได้โปรแกรมแก้ไขจริง การเติมข้อความอัตโนมัติที่รู้ schema และโครงร่าง endpoint ที่ปรากฏในแถบด้านข้างขณะที่คุณพิมพ์ หากคุณเคยใช้ VS Code กับส่วนขยาย OpenAPI มาบ้าง สิ่งนี้จะให้ความรู้สึกคุ้นเคย — ยกเว้นว่าโครงร่างจะเชื่อมโยงกับการนำทาง และการคลิกที่ endpoint จะกระโดดไปยังบรรทัดที่ถูกต้อง
5. Commit และ push มุมบนขวา, Commit & Push กล่องโต้ตอบจะเปิดไปยังส่วน Changes ที่แสดงรายการไฟล์ที่แก้ไข ช่อง Commit Message และสองปุ่ม: Push หรือ Discard all changes ไม่มีขั้นตอนการจัดเตรียมแยกต่างหาก — สิ่งใดก็ตามที่อยู่ใน Changes จะถูก commit นั่นเป็นการทำให้ง่ายขึ้นโดยเจตนา และสำหรับเวิร์กโฟลว์การแก้ไข spec ส่วนใหญ่ มันเป็นการตัดสินใจที่ถูกต้อง
6. ดูตัวบ่งชี้การซิงค์ มุมล่างซ้าย — คุณจะเห็นมันเป็น Synced just now ในรูปที่ 1 มันจะบอกคุณว่าการแก้ไขในเครื่องของคุณถูก push, pull หรือไม่ซิงค์กับรีโมท ผมเปิดทิ้งไว้ที่มุมจอ และมันกลายเป็นสิ่งที่ผมเชื่อถือมากกว่ากล่องโต้ตอบ หากตัวบ่งชี้เป็นสีเขียว แสดงว่าคุณและที่เก็บข้อมูลตรงกัน
นั่นคือทั้งหมดของขอบเขตการใช้งาน หกขั้นตอน ไม่มีเอนจิ้นการซิงค์แยกต่างหากให้กำหนดค่า ไม่มีปลั๊กอินให้ติดตั้ง
สิ่งที่ผมสังเกตเห็นที่เอกสารไม่ได้บอกคุณ
มีสามสิ่งที่ควรเน้น ซึ่งทั้งหมดมาจากการทดลองใช้ในตอนเช้า
มุมมองโครงร่างอัปเดตเร็วกว่าที่ผมคาดไว้ ผมเคยใช้ "live OpenAPI editors" มาหลายตัวในอดีต และส่วนใหญ่จะทำการวิเคราะห์ใหม่เมื่อบันทึก ซึ่งหมายความว่าจะมีการหน่วงเวลา 30 วินาทีระหว่างการเพิ่ม endpoint และการเห็นมันในแถบด้านข้าง โครงร่างของ Apidog อัปเดตในขณะที่ผมพิมพ์ — เร็วพอจนผมเลิกตรวจสอบแล้ว นั่นฟังดูเหมือนเป็นเรื่องเล็กน้อย แต่มันไม่ใช่ มันคือความแตกต่างระหว่างการเชื่อถือโครงร่างเป็นเครื่องมือนำทางกับการตรวจสอบเป็นรายงานสถานะ
การรวม Git เป็นแบบสองทางอย่างแท้จริง ผมแก้ไขไฟล์เดียวกันในเครื่องของผมและ push จากเทอร์มินัลในขณะที่ Apidog เปิดอยู่ Apidog สังเกตเห็น ตัวบ่งชี้การซิงค์เปลี่ยนเป็น "behind" และการคลิกครั้งเดียวก็ดึงการเปลี่ยนแปลงเข้าสู่โปรแกรมแก้ไขโดยไม่มีกล่องโต้ตอบการรวมกัน การซิงค์แบบสองทางที่เอกสารสัญญาไว้คือประสบการณ์จริง ไม่ใช่สรุปการตลาด หากคุณมีเพื่อนร่วมทีมที่ไม่ยอมใช้อะไรนอกจาก Vim พวกเขาก็ยังคงใช้ Vim ได้ และคุณก็ยังคงใช้ Apidog ได้ และไฟล์ในที่เก็บก็จะยังคงเป็นสิ่งเดียวที่ทั้งสองคนกำลังแก้ไขอยู่
ไม่มีทางย้อนกลับไปใช้เครื่องมือออกแบบภาพในโปรเจกต์เดียวกัน นี่เป็นเจตนา แต่ก็ควรทราบก่อนที่คุณจะ commit หากคุณเลือก Spec-First Mode ในตอนสร้าง โปรเจกต์นั้นจะเป็น spec-first คุณไม่สามารถสลับโปรเจกต์กลางคันได้เพราะโมเดลข้อมูลเบื้องหลังแตกต่างกัน สำหรับทีมที่ต้องการทั้งสองโหมดบน spec เดียวกัน เวิร์กโฟลว์คือ: เก็บ spec ไว้ในที่เก็บข้อมูล ชี้โปรเจกต์ Spec-First ไปที่มัน และให้ผู้ใช้โหมดภาพเปิดโปรเจกต์แยกต่างหากที่นำเข้าจากแหล่งเดียวกัน ไม่ใช่แบบไร้รอยต่อ แต่ใช้งานได้
เหมาะกับสถานการณ์ไหน และไม่เหมาะกับสถานการณ์ไหน
ผมจะใช้สิ่งนี้ในการผลิต นั่นคือคำตอบที่ตรงไปตรงมาที่สุดที่ผมสามารถให้ได้ การผสมผสานของโปรแกรมแก้ไขจริง การเติมข้อความอัตโนมัติที่เคารพ OpenAPI schema และตัวบ่งชี้การซิงค์ที่ผมสามารถเชื่อถือได้ คือสิ่งที่ผมต้องการจาก Apidog มาสองปีแล้ว
แต่นี่คือเวอร์ชันที่ซื่อสัตย์ว่าสิ่งนี้เหมาะกับใคร
มันเหมาะถ้าคุณเขียน OpenAPI ด้วยมืออยู่แล้ว หรือต้องการที่จะทำ มันเหมาะถ้า CI ของคุณรัน `spectral lint` หรือสร้าง client SDK จาก spec และ spec จำเป็นต้องอยู่ใน Git อยู่แล้ว มันเหมาะถ้าคุณมีวิศวกรในทีมที่จะเปิด pull request กับไฟล์ YAML จาก VS Code และคุณต้องการให้ทุกคนใช้เครื่องมือเดียวกันโดยไม่บังคับให้พวกเขาเลิกใช้คีย์บอร์ด และมันเหมาะอย่างยิ่งถ้าคุณจัดการความคลาดเคลื่อนระหว่าง "spec ใน Apidog" และ "spec ใน repo" ด้วยขั้นตอน `make export` ที่ไม่มีใครเชื่อถือ
มันไม่เหมาะถ้าทีมของคุณไม่เคยแตะ OpenAPI และเครื่องมือออกแบบภาพเป็นเหตุผลที่ทำให้พวกเขาสามารถมีส่วนร่วมได้ สำหรับทีมเหล่านั้น โหมดเริ่มต้นยังคงเป็นตัวเลือกที่ถูกต้อง Spec-First Mode แลกความง่ายในการเริ่มต้นใช้งานกับความแม่นยำ และการแลกเปลี่ยนนั้นผิดพลาดเมื่อผู้ร่วมให้ข้อมูลส่วนใหญ่ของคุณไม่ใช่ผู้เชี่ยวชาญด้าน API
มันยังไม่เหมาะสำหรับทีมที่ต้องการผสมผสานทั้งสองโหมดในโปรเจกต์เดียวกัน รุ่นเบต้าเป็นเวอร์ชันเบต้าอย่างแท้จริงในส่วนนี้ ผมคาดว่าสิ่งนี้จะดีขึ้นในไม่กี่รุ่นถัดไป
ประเด็นสำคัญ
การพัฒนาแบบ Spec-first เคยหมายถึงการปฏิเสธเครื่องมือออกแบบ API คุณจะอยู่กับ YAML และละทิ้ง test runners และ mock servers หรือคุณจะอยู่ในเครื่องมือออกแบบภาพและละทิ้ง Git ในฐานะแหล่งความจริง สิ่งที่น่าสนใจใน Spec-First Mode คือ Apidog หยุดขอให้คุณเลือกว่าจะเอาแบบไหน
ไฟล์ใน repo ของคุณคือไฟล์ในโปรแกรมแก้ไข โครงร่างคือมุมมอง ไม่ใช่สถานะ การซิงค์ Git คือสายเชื่อม ไม่ใช่คุณสมบัติ หากคุณกำลังรอแพลตฟอร์ม API ที่ให้ความสำคัญกับ spec-first อย่างจริงจัง แทนที่จะถือว่าเป็นตัวเลือกการส่งออก นี่คือสิ่งที่คุณควรลอง
เวอร์ชันเบต้าใช้งานได้แล้วในกล่องโต้ตอบ New Project วันนี้ ดาวน์โหลด Apidog เลือก Spec-First Mode ในตอนสร้าง และชี้ไปที่ repo ที่คุณเชื่อถืออยู่แล้ว การ commit ครั้งแรกใช้เวลาสิบนาที การตัดสินใจว่าจะเก็บไว้หรือไม่ใช้เวลาประมาณหนึ่งสัปดาห์
button