การทำงานร่วมกันผ่าน API ไม่จำเป็นต้องเปิดแอปหนัก ๆ รอซิงค์ หรือไล่คลิกหลายแผงเพื่อดูการเปลี่ยนแปลงของทีม หาก API ของคุณอธิบายด้วยไฟล์ OpenAPI งานหลักคือการกำหนดเวอร์ชันของสเปก, ตรวจสอบ diff และรวมการเปลี่ยนแปลง ซึ่งทั้งหมดทำได้จากเทอร์มินัล
คู่มือนี้รวม CLI น้ำหนักเบาสำหรับงานทั้งสามด้าน: ติดตั้งเร็ว, รันด้วยคำสั่งเดียว และนำไปใช้กับ Git หรือ CI ได้ทันที ไม่มี GUI และไม่มี daemon ที่ต้องรันค้างไว้ หากต้องการดูภาพรวมเวิร์กโฟลว์สำหรับทีมก่อน อ่านบทความเกี่ยวกับ เครื่องมือการทำงานร่วมกันผ่าน API ได้เช่นกัน
กรอบคิดมีเพียงสามส่วน:
- กำหนดเวอร์ชันของสเปก — ระบุว่าใครแก้ไขอะไรและใช้เวอร์ชันใด
- ตรวจสอบการเปลี่ยนแปลง — ดูว่า API เปลี่ยนอะไร และมี breaking change หรือไม่
- รวมการเปลี่ยนแปลงร่วมกัน — นำการแก้ไขผ่าน review ไปยังแหล่งความจริงของทีม
เครื่องมือทั้งหมดในบทความนี้อ่านหรือเขียนตาม มาตรฐาน OpenAPI จึงใช้ไฟล์สเปกร่วมกันได้โดยไม่ล็อกอินกับเครื่องมือใดเครื่องมือหนึ่ง
อะไรทำให้ CLI “น้ำหนักเบา” สำหรับการทำงานร่วมกันผ่าน API
CLI ที่เหมาะกับงานนี้ควรมีคุณสมบัติดังนี้:
-
ติดตั้งน้อย — เป็นไบนารีเดียว, รันผ่าน
npxหรือใช้npm install -gครั้งเดียว - เริ่มต้นเร็ว — รันเสร็จแล้ว exit ทันที จึงเหมาะกับ script, hook และ CI
-
ตั้งค่าน้อย — ชี้ไปที่
openapi.yamlแล้วทำงานได้ - ใช้เทอร์มินัลเป็นหลัก — ผลลัพธ์อ่านได้ใน shell หรือส่งต่อให้ CI ได้
- ทำงานเฉพาะด้านได้ดี — เช่น diff, lint, publish หรือ merge
ด้านล่างเรียงจากเครื่องมือพื้นฐานที่สุด ไปจนถึง CLI ที่รวมเวิร์กโฟลว์ระดับโปรเจกต์ไว้ในตัวเดียว
Git + ไฟล์สเปก: จุดเริ่มต้นที่ควรมี
เริ่มจากเก็บไฟล์ OpenAPI ไว้ใน repository เดียวกับโค้ด Git จะให้ประวัติ, commit, diff และ Pull Request โดยไม่ต้องเพิ่มเครื่องมือใหม่
# เพิ่มสเปกเข้า repo และตรวจสอบการเปลี่ยนแปลงเหมือนโค้ดทั่วไป
git add openapi.yaml
git commit -m "เพิ่มพารามิเตอร์การแบ่งหน้าให้กับ GET /orders"
git diff main -- openapi.yaml
เวิร์กโฟลว์ที่แนะนำ:
- แก้ไข
openapi.yamlใน feature branch - commit การเปลี่ยนแปลงพร้อมข้อความที่ระบุ endpoint หรือ contract ที่เปลี่ยน
- เปิด Pull Request
- ให้ผู้ตรวจสอบคอมเมนต์บนบรรทัดของสเปก
- merge เมื่อผ่าน review และ CI
นี่คือแนวคิดของ การทำงานร่วมกันผ่าน API แบบ Git-native
ดีที่สุดสำหรับ: ประวัติการเปลี่ยนแปลงและ code review โดยไม่ต้องติดตั้งอะไรเพิ่ม
ข้อจำกัด: Git diff บน YAML เป็น text diff จึงอาจมี noise จากการจัด indent หรือเรียง key ใหม่ แม้ความหมายของ API จะไม่เปลี่ยน ใช้ semantic diff tool เพิ่มเติมเพื่อแก้ปัญหานี้
oasdiff: กัน breaking change ใน CI
oasdiff เป็น Go binary สำหรับเปรียบเทียบ OpenAPI สองเวอร์ชัน และรายงานว่าเกิด breaking change หรือไม่ เหมาะสำหรับใช้เป็น merge gate เพราะสามารถทำให้ CI ล้มเหลวผ่าน exit code ได้
# ติดตั้งบน macOS
brew install oasdiff
# ตรวจสอบว่าสเปกใน PR ทำให้ client เดิมใช้งานไม่ได้หรือไม่
oasdiff breaking main-spec.yaml pr-spec.yaml
# exit 0 = ไม่พบ breaking change
# exit 1 = พบ breaking change
หากต้องการ changelog สำหรับใส่ใน PR description หรือ CI log:
oasdiff changelog main-spec.yaml pr-spec.yaml
ตัวอย่าง GitHub Actions แบบสั้น:
- name: Check OpenAPI breaking changes
run: oasdiff breaking openapi-main.yaml openapi.yaml
ดีที่สุดสำหรับ: ทำ breaking-change gate ก่อน merge
ข้อจำกัด: ทำหน้าที่ diff และ report เป็นหลัก ไม่ได้จัดการ branch, review หรือเผยแพร่เอกสาร
Optic: รีวิว OpenAPI diff แบบมีโครงสร้าง
Optic เป็น CLI จาก npm สำหรับ diff, lint และ review การเปลี่ยนแปลง OpenAPI โดยออกแบบให้เข้ากับ Git workflow รองรับโครงสร้าง schema เช่น $ref, oneOf และ allOf
# ติดตั้ง
npm install -g @useoptic/optic
# เปรียบเทียบสเปกปัจจุบันกับสเปกใน main branch
optic diff openapi.yaml --base main --check
ใช้ Optic เมื่อคุณต้องการให้ PR แสดงผลการเปลี่ยนแปลงในระดับ API เช่น endpoint, parameter, request body หรือ response schema แทนที่จะเป็นเพียงบรรทัด YAML ที่เปลี่ยนไป
ดีที่สุดสำหรับ: รีวิว PR ที่ต้องการกฎชัดเจนว่าอะไรคือ breaking change หรือการเปลี่ยนแปลงที่ไม่อนุญาต
ข้อจำกัด: ใช้ Node.js จึงหนักกว่า Go binary และควรตั้งค่า rules เพื่อให้ได้ประโยชน์สูงสุด
Bump.sh CLI: เผยแพร่เอกสารและสร้าง changelog
Bump.sh CLI ใช้เผยแพร่เอกสาร API จากเทอร์มินัล และเปรียบเทียบสเปกในเครื่องกับเวอร์ชันที่เผยแพร่แล้ว เหมาะเมื่อทีมต้องการเอกสาร reference กลางที่อัปเดตตามสเปก
# ติดตั้ง
npm install -g bump-cli
# เผยแพร่เอกสาร API เวอร์ชันใหม่
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN
# ดู changelog ระหว่างสเปกในเครื่องกับเวอร์ชันที่เผยแพร่
bump diff openapi.yaml --doc my-api
นำผลลัพธ์จาก bump diff ไปใส่ใน Pull Request ได้ เพื่อให้ผู้ตรวจสอบเห็นสรุปการเปลี่ยนแปลงโดยไม่ต้องเปิดไฟล์ YAML ทั้งหมด
ดีที่สุดสำหรับ: เอกสาร API ที่ใช้ร่วมกันและอัปเดตต่อเนื่อง พร้อม diff สำหรับ review
ข้อจำกัด: เอกสารโฮสต์และการ deploy เป็นบริการแบบชำระเงินของ Bump.sh ส่วน CLI เป็น client ที่เชื่อมต่อกับแพลตฟอร์ม
Redocly CLI: lint, bundle และ push สเปก
Redocly CLI เป็นชุดเครื่องมือ OpenAPI ที่ครอบคลุมงาน lint, bundle และ push สเปกไปยัง registry ใช้ได้ดีเมื่อสเปกถูกแยกเป็นหลายไฟล์ด้วย $ref
# รันโดยไม่ต้องติดตั้งแบบ global
npx @redocly/cli lint openapi.yaml
# รวมไฟล์สเปกและ $ref เป็น artifact เดียว
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
ก่อน publish ควร lint และ bundle ใน CI:
npx @redocly/cli lint openapi.yaml
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
จากนั้นจึง push เวอร์ชันที่ผ่านการตรวจสอบไปยัง registry ที่ใช้ร่วมกัน:
# ต้องใช้ API key
npx @redocly/cli push openapi.yaml --organization "Acme" --project "orders-api"
ดีที่สุดสำหรับ: บังคับ style guide ของ OpenAPI, รวมสเปกหลายไฟล์ และส่งสเปกไปยัง registry กลาง
ข้อจำกัด: lint และ bundle ทำงานในเครื่องได้ฟรี แต่ push และ registry เป็นส่วนหนึ่งของแพลตฟอร์มโฮสต์ สำหรับเวิร์กโฟลว์การแก้ไขสเปกร่วมกัน ดูคู่มือ การแก้ไขสเปก API แบบทำงานร่วมกัน
GitHub CLI (gh): เปิดและจัดการ PR จาก shell
ถ้าทีมทำงานบน GitHub อยู่แล้ว GitHub CLI ทำให้คุณเปิด PR, ขอ reviewer และตรวจสอบสถานะได้จากเทอร์มินัล
# เปิด Pull Request สำหรับการเปลี่ยนแปลงสเปก
gh pr create \
--title "เพิ่มการแบ่งหน้า /orders" \
--body "เพิ่มพารามิเตอร์ page และ limit"
# อนุมัติ PR
gh pr review --approve
จับคู่ gh กับ oasdiff หรือ Optic เพื่อให้ review flow และ semantic API validation เกิดใน pipeline เดียวกัน
ตัวอย่างลำดับการทำงาน:
oasdiff breaking openapi-main.yaml openapi.yaml
gh pr create --title "อัปเดต OpenAPI contract"
ดีที่สุดสำหรับ: จัดการ review และ merge flow จาก shell
ข้อจำกัด: gh เข้าใจ Pull Request แต่ไม่เข้าใจ semantic ของ API จึงควรใช้ร่วมกับ oasdiff หรือ Optic
Apidog CLI: เวิร์กโฟลว์ branch, review และ merge แบบรวมศูนย์
Apidog CLI เป็น CLI ระดับโปรเจกต์ที่เข้าถึงทรัพยากรการออกแบบ API, เวอร์ชัน และการทำงานร่วมกันใน Apidog จากเทอร์มินัล จุดที่เกี่ยวข้องกับ collaboration คือคำสั่ง branch, merge-request และ git-connection
Apidog ไม่ใช่โอเพนซอร์ส แต่มีเวอร์ชันฟรี หากคุณต้องการเวิร์กโฟลว์ที่รวมสาขาสเปก, review และ Git backup โดยไม่ต้องประกอบหลายเครื่องมือเข้าด้วยกัน CLI นี้ครอบคลุมงานดังกล่าวในชุดคำสั่งเดียว
เริ่มต้นด้วยการติดตั้งและยืนยันตัวตน:
npm install -g apidog-cli
apidog login --with-token $APIDOG_TOKEN
สร้าง branch สำหรับการเปลี่ยนแปลง API:
# สร้าง sprint branch สำหรับงานที่มีขอบเขตชัดเจน
apidog branch create --type sprint --name "orders-pagination"
แฟล็ก --type รองรับโมเดล branch หลายแบบ:
-
sprintสำหรับฟีเจอร์หรือรีลีสที่มีขอบเขตชัดเจน -
generalสำหรับงานต่อเนื่อง -
aiสำหรับแยกงานที่ agent แก้ไขทรัพยากรโดยไม่แตะ source หลัก
เมื่อแก้ไขเสร็จ ให้ส่ง merge request แทนการ merge ตรง:
# ส่งเฉพาะ endpoint ที่ต้องการให้ตรวจสอบ
apidog merge-request create \
--branch "orders-pagination" \
--endpoint-ids 1,2
เชื่อมต่อสเปกของโมดูลเข้ากับ Git repository เพื่อเก็บ backup และประวัติร่วมกับโค้ด:
apidog git-connection --help
CLI ส่งผลลัพธ์แบบ JSON พร้อม agentHints.nextSteps จึงนำไปต่อกับ script หรือ AI agent ได้สะดวก ดูคำสั่งทั้งหมดได้ใน คู่มือฉบับสมบูรณ์ของ Apidog CLI
ดีที่สุดสำหรับ: เวิร์กโฟลว์ versioning + review + merge แบบบูรณาการ รวมถึง branch model สำหรับทีมและ agent
ข้อจำกัด: เป็น CLI ของแพลตฟอร์ม จึงต้องสื่อสารกับโปรเจกต์ Apidog ไม่ได้ทำงานกับไฟล์ local แบบล้วน ๆ และไม่มี OpenAPI linter ในตัว ใช้ Redocly หรือ Spectral สำหรับ style rules เพิ่มเติมได้ หากต้องการควบคุมสิทธิ์ตามบทบาท ดู การทำงานร่วมกันผ่าน API อย่างปลอดภัยด้วย RBAC
วิธีเลือกเครื่องมือ
เลือกจากงานที่ต้องทำ ไม่ใช่เลือกเครื่องมือก่อนแล้วค่อยปรับ workflow ตาม
| เครื่องมือ | เหมาะที่สุดสำหรับ | การติดตั้ง | โอเพนซอร์ส? | หมายเหตุ |
|---|---|---|---|---|
| Git + ไฟล์สเปก | ประวัติและ review โดยไม่เพิ่มเครื่องมือ | มีอยู่แล้ว | ใช่ (Git) | YAML diff อาจมี noise; ใช้ semantic diff ร่วมกัน |
| oasdiff | merge gate สำหรับ breaking change | brew install oasdiff |
ใช่ (Apache 2.0) | exit code ทำให้ CI ล้มเหลวได้ |
| Optic | รีวิว API change แบบมีโครงสร้างใน PR | npm i -g @useoptic/optic |
ใช่ (MIT) | รองรับ $ref, oneOf, allOf
|
| Bump.sh CLI | เผยแพร่เอกสารร่วมกันและดู diff | npm i -g bump-cli |
CLI โอเพนซอร์ส, โฮสติ้งมีค่าใช้จ่าย | ต้องใช้ Node 20+ |
| Redocly CLI | lint, bundle และ push ไป registry | npx @redocly/cli |
CLI โอเพนซอร์ส, registry มีค่าใช้จ่าย |
push ต้องใช้ API key |
| GitHub CLI | ขับเคลื่อน PR review จาก shell | brew install gh |
ใช่ (MIT) | จัดการ PR ไม่ได้ตรวจ semantic API |
| Apidog CLI | versioning + review + merge แบบรวมศูนย์ | npm i -g apidog-cli |
ไม่ใช่โอเพนซอร์ส; มีเวอร์ชันฟรี | มี branch, merge-request, git-connection
|
ทีมส่วนใหญ่มักใช้หลายเครื่องมือร่วมกัน ตัวอย่างสแต็กที่เริ่มได้ทันที:
- เก็บ
openapi.yamlใน Git - รัน oasdiff หรือ Optic ใน CI ก่อน merge
- ใช้
ghสำหรับเปิดและจัดการ PR - ใช้ Bump.sh หรือ Redocly เมื่อต้องเผยแพร่เอกสาร
- ใช้ Apidog CLI หากต้องการจัดการ branch, review และ merge จาก CLI เดียว
สำหรับการเปรียบเทียบตัวเลือกในระดับทีม ดู เครื่องมือการทำงานร่วมกันผ่าน API สำหรับทีม
สรุป
การทำงานร่วมกันผ่าน API จากเทอร์มินัลแบ่งเป็นสามขั้นตอน:
- กำหนดเวอร์ชันของสเปก ด้วย Git
- ตรวจสอบ semantic diff ด้วย oasdiff หรือ Optic
- review และ merge การเปลี่ยนแปลง ผ่าน GitHub CLI, registry หรือแพลตฟอร์มที่ใช้ร่วมกัน
Git เป็นฐานที่ทุกทีมควรเริ่มต้น, oasdiff และ Optic ช่วยป้องกัน contract break, Bump.sh และ Redocly ช่วยเผยแพร่ผลลัพธ์ ส่วน Apidog CLI รวมการกำหนดเวอร์ชัน การตรวจสอบ และการรวมไว้ใน workflow เดียว
หากต้องการเส้นทางแบบรวมศูนย์โดยไม่ต้องประกอบเครื่องมือเอง ให้ ดาวน์โหลด Apidog, ติดตั้ง apidog-cli แล้วเริ่มด้วย apidog branch create และ apidog merge-request จากเทอร์มินัลที่คุณใช้อยู่แล้ว จากนั้นค่อยเชื่อมต่อคำสั่งเหล่านี้เข้ากับ CI ของทีม
Top comments (1)
เรื่องของการทำงานร่วมกันผ่าน API นั้นเป็นเรื่องที่น่าสนใจมาก โดยเฉพาะอย่างยิ่งเมื่อเราพูดถึงเรื่องของการกำหนดเวอร์ชันของสเปก การตรวจสอบการเปลี่ยนแปลง และการรวมการเปลี่ยนแปลงร่วมกัน ฉันพบว่าการใช้เครื่องมือ CLI น้ำหนักเบา เช่น oasdiff เป็นวิธีที่ดีในการป้องกัน breaking change ใน CI และทำให้การทำงานร่วมกันผ่าน API มีประสิทธิภาพมากขึ้น ฉันเคยใช้ oasdiff ในโปรเจกต์ของตัวเองและพบว่ามันช่วยให้การตรวจสอบการเปลี่ยนแปลงของ API มีประสิทธิภาพมากขึ้น และช่วยลดความเสี่ยงของ breaking change ได้ อย่างไรก็ตาม ฉันก็อยากทราบว่าเรามีวิธีอื่น ๆ อีกหรือไม่ในการทำงานร่วมกันผ่าน API ที่ไม่ต้องใช้เครื่องมืออื่น ๆ เพิ่มเติม และยังคงรักษาความง่ายและความมีประสิทธิภาพในการทำงานร่วมกัน