Cộng tác API trước đây có nghĩa là mở một ứng dụng nặng nề, chờ nó đồng bộ hóa và nhấp qua các bảng điều khiển để xem đồng đội đã thay đổi những gì. Bạn không cần bất kỳ điều nào trong số đó. Nếu API của bạn được mô tả bằng một tệp OpenAPI, hầu hết công việc cộng tác thực sự là công việc liên quan đến văn bản: tạo phiên bản cho đặc tả, xem xét sự khác biệt và hợp nhất một thay đổi được chia sẻ. Tất cả đều phù hợp với terminal.
Hướng dẫn này bao gồm các công cụ CLI nhẹ xử lý ba công việc đó. Mọi công cụ ở đây đều cài đặt trong vài giây, chạy từ một lệnh duy nhất và tích hợp vào Git hoặc CI. Không có GUI, không có dịch vụ nền, không cần thiết lập chỗ ngồi cho toàn bộ nhóm chỉ để đọc nhật ký thay đổi. Để có cái nhìn đầy đủ hơn về quy trình làm việc của nhóm, hãy bắt đầu với tổng hợp của chúng tôi về các công cụ cộng tác API; bài viết này là tập hợp con ưu tiên terminal.
Đây là khuôn khổ. Cộng tác từ dòng lệnh được chia thành phiên bản đặc tả (ai có phiên bản nào), xem xét (những gì đã thay đổi và liệu nó có an toàn không) và các thay đổi được chia sẻ (hợp nhất các chỉnh sửa của một người vào nguồn đáng tin cậy của mọi người). Mỗi công cụ dưới đây thực hiện tốt một hoặc hai trong số đó. Đặc tả OpenAPI là tiêu chuẩn chính thức mà các công cụ này đọc và ghi, vì vậy đây là ngôn ngữ chung giúp toàn bộ hoạt động. Bạn sẽ nhận được bảy công cụ, một lệnh cài đặt và ví dụ thực tế cho mỗi công cụ, cùng với một bảng ngắn để lựa chọn.
Điều gì làm cho một công cụ CLI trở nên “nhẹ” cho việc cộng tác API
Nhẹ là một tiêu chuẩn thực sự, không phải là một cảm giác. Một công cụ đạt tiêu chuẩn khi nó đáp ứng hầu hết các tiêu chí sau:
- Cài đặt nhỏ. Một tệp thực thi duy nhất, một lệnh gọi
npx, hoặc mộtnpm install -g. Không có trình cài đặt, không có dịch vụ chạy nền. - Khởi động nhanh. Nó chạy và thoát, vì vậy bạn có thể gọi nó trong một tập lệnh hoặc một hook pre-commit.
- Cấu hình thấp. Nó hoạt động với một tệp OpenAPI thuần túy mà không cần thiết lập hoặc thiết lập tối thiểu. Chỉ cần trỏ nó vào
openapi.yamlvà sử dụng. - Ưu tiên Terminal. Đầu ra được thiết kế để đọc trong terminal hoặc chuyển vào CI, chứ không phải hiển thị trên một bảng web.
- Thực hiện tốt một công việc. So sánh sự khác biệt, xuất bản hoặc hợp nhất; không phải là một nền tảng toàn diện mà bạn phải áp dụng.
Các công cụ chạy đại khái từ nhỏ nhất và tập trung nhất đến tích hợp nhất. Mục cuối cùng là ngoại lệ: một CLI dự án đầy đủ thay vì một tệp thực thi đơn mục đích, được bao gồm vì nó bao gồm việc tạo phiên bản, xem xét và hợp nhất tại một nơi.
Git + tệp đặc tả (cơ bản)
Công cụ cộng tác nhẹ nhất là công cụ bạn đã có. Cam kết tệp OpenAPI của bạn vào kho lưu trữ bên cạnh mã, và Git xử lý việc tạo phiên bản, lịch sử và xem xét miễn phí. Một yêu cầu kéo (pull request) đối với openapi.yaml hiển thị chính xác các dòng đã thay đổi, đồng đội bình luận về các dòng đó, và việc hợp nhất là thay đổi được chia sẻ. Đây là toàn bộ ý tưởng đằng sau cộng tác API Git-native.
# Track the spec in the repo, then review changes like any code
git add openapi.yaml
git commit -m "Add pagination params to GET /orders"
git diff main -- openapi.yaml
Tốt nhất ở: lịch sử và xem xét mà không cần công cụ mới. Mọi nhà phát triển đều đã biết nó.
Hạn chế thực tế: các diff Git thô trên YAML rất ồn ào. Một khóa được sắp xếp lại hoặc một khối được thụt lề lại trông giống như một thay đổi ngay cả khi API giống hệt nhau. Đó chính xác là khoảng trống mà các công cụ tiếp theo lấp đầy: chúng so sánh ý nghĩa của API, không phải văn bản của tệp.
oasdiff
oasdiff là một tệp thực thi Go duy nhất so sánh hai đặc tả OpenAPI và cho bạn biết liệu thay đổi đó có gây lỗi (breaking change) hay không. Nó là mã nguồn mở (Apache 2.0), phát hiện hàng trăm loại thay đổi khác nhau, và mã thoát của nó làm cho việc kiểm soát một hợp nhất trở nên dễ dàng. Chạy nó trong CI và một thay đổi gây lỗi sẽ làm thất bại bản dựng trước khi nó đến tay đồng đội.
# Install (macOS)
brew install oasdiff
# Fail the build if the new spec breaks existing clients
oasdiff breaking main-spec.yaml pr-spec.yaml
# exit 0 = safe, exit 1 = breaking changes found
Sử dụng oasdiff changelog base.yaml revision.yaml để có bản tóm tắt dễ đọc về tất cả những gì đã thay đổi, dù có gây lỗi hay không.
Tốt nhất ở: phát hiện thay đổi gây lỗi như một cổng hợp nhất. Nhanh chóng, có thể lập trình, không cần tài khoản.
Hạn chế thực tế: nó so sánh và báo cáo; nó không xuất bản tài liệu hay quản lý nhánh. Nó là một công việc sắc bén, được thực hiện tốt.
Optic
Optic là một CLI được cài đặt qua npm dùng để so sánh, lint và xem xét các thay đổi OpenAPI với quy trình làm việc Git. Nó được cấp phép MIT và hiểu $ref, oneOf, allOf cùng các dạng lược đồ khác mà các công cụ so sánh đơn giản dễ mắc lỗi. Trong khi oasdiff cung cấp cho bạn một cổng vượt qua/thất bại, Optic tập trung vào cuộc trò chuyện xem xét: nó có thể so sánh đặc tả đang làm việc của bạn với phiên bản trên nhánh chính và tóm tắt các thay đổi cấp API cho một PR.
# Install
npm install -g @useoptic/optic
# Compare the current spec against the one on main
optic diff openapi.yaml --base main --check
Tốt nhất ở: xem xét thay đổi có cấu trúc trong các yêu cầu kéo, với các quy tắc về những gì được coi là thay đổi gây lỗi hoặc bị cấm.
Hạn chế thực tế: nó dựa trên Node, vì vậy nó nặng hơn một tệp thực thi Go duy nhất, và để tận dụng tối đa nó có nghĩa là phải áp dụng các quy tắc cấu hình và kiểm tra của nó.
Bump.sh CLI
Bump.sh CLI xuất bản và so sánh tài liệu API từ terminal. Cộng tác ở đây là về tài liệu được chia sẻ, luôn cập nhật: bạn deploy một phiên bản mới khi đặc tả thay đổi, và đồng đội cùng người tiêu dùng đọc cùng một tài liệu tham khảo được hiển thị. Lệnh diff đăng một nhật ký thay đổi giữa phiên bản đã xuất bản và tệp cục bộ của bạn, điều này hữu ích để đưa vào bình luận PR. Nó là một gói Node (bump-cli), yêu cầu Node 20+ và preview và diff hoạt động mà không cần token.
# Install
npm install -g bump-cli
# Publish a new version of the shared docs
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN
# Or just get the changelog between versions
bump diff openapi.yaml --doc my-api
Tốt nhất ở: giữ một tài liệu được chia sẻ, dễ đọc đồng bộ với đặc tả, cộng với so sánh sự khác biệt trong terminal để xem xét.
Hạn chế thực tế: các tài liệu được lưu trữ và quy trình triển khai là một sản phẩm trả phí của Bump.sh. CLI là ứng dụng khách; bề mặt được chia sẻ nằm trên nền tảng của họ.
Redocly CLI
Redocly CLI là một bộ công cụ OpenAPI rộng lớn: nó kiểm tra cú pháp (lint), đóng gói (bundle) và đẩy các đặc tả lên Redocly registry (hiện là Reunite). Lệnh push là đòn bẩy cộng tác; nó tải lên một phiên bản đặc tả lên một registry được chia sẻ để phần còn lại của tổ chức kéo từ một nguồn chuẩn thay vì truyền tệp xung quanh. Việc đóng gói cũng quan trọng, vì một đặc tả đa tệp với $refs trở thành một artifact gọn gàng mà đồng đội của bạn có thể sử dụng.
# No install needed; run via npx
npx @redocly/cli lint openapi.yaml
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
# Push a version to the shared registry (needs an API key)
npx @redocly/cli push openapi.yaml --organization "Acme" --project "orders-api"
Tốt nhất ở: kiểm tra cú pháp theo phong cách chung và đẩy một đặc tả duy nhất, đáng tin cậy đến một registry được chia sẻ.
Hạn chế thực tế: lint và bundle là miễn phí và cục bộ, nhưng push và registry là một phần của nền tảng lưu trữ của Redocly. Để có quy trình làm việc chỉnh sửa đặc tả sâu hơn, hãy xem hướng dẫn của chúng tôi về chỉnh sửa đặc tả API cộng tác.
GitHub CLI (gh)
Nếu quá trình xem xét của bạn diễn ra trong các yêu cầu kéo (pull request), GitHub CLI mang toàn bộ quy trình đó đến terminal. Bạn mở PR thay đổi đặc tả, yêu cầu người xem xét và kiểm tra trạng thái mà không cần mở trình duyệt. Kết hợp nó với oasdiff hoặc Optic trong một Git hook và việc xem xét đặc tả trở thành một phần bình thường, có thể lập trình được của quá trình xem xét mã.
# Open a PR for the spec change and tag reviewers
gh pr create --title "Add /orders pagination" --body "Adds page + limit params"
gh pr review --approve
Tốt nhất ở: thúc đẩy cuộc trò chuyện xem xét và hợp nhất từ shell khi nhóm của bạn đã sử dụng GitHub.
Hạn chế thực tế: nó quản lý PR, không phải ngữ nghĩa API. Nó không biết liệu một thay đổi có gây lỗi hay không; đó là lý do bạn kết nối oasdiff hoặc Optic vào.
Apidog CLI
Apidog CLI là một ngoại lệ ở đây. Nó không phải là một tệp thực thi đơn mục đích; nó là một CLI tài nguyên dự án đầy đủ (npm install -g apidog-cli) truy cập cùng dữ liệu thiết kế, phiên bản và cộng tác như nền tảng Apidog, từ terminal. Để cộng tác, ba nhóm lệnh quan trọng là: branch, merge-request và git-connection.
Apidog không phải là mã nguồn mở; nó là một sản phẩm thương mại có gói miễn phí. Nhưng nếu bạn không muốn tự tay ghép nối một công cụ so sánh, một trình xuất bản tài liệu và một registry, thì gói miễn phí cùng với CLI sẽ cung cấp cho bạn các nhánh đặc tả, một quy trình xem xét và một bản sao lưu Git tại một nơi.
Bắt đầu với một nhánh riêng biệt. Cờ --type chọn mô hình nhánh: sprint cho một tính năng hoặc bản phát hành cụ thể, general cho công việc đang diễn ra, hoặc ai cho một nhánh riêng biệt nơi một tác nhân chỉnh sửa tài nguyên mà không chạm vào mã nguồn của bạn.
# Install and authenticate
npm install -g apidog-cli
apidog login --with-token $APIDOG_TOKEN
# Start a sprint branch for a shared change
apidog branch create --type sprint --name "orders-pagination"
Khi nhánh đã sẵn sàng, hãy mở một yêu cầu hợp nhất (merge request) thay vì hợp nhất trực tiếp. Đây là cổng xem xét: khi nhánh chính được bảo vệ, một biên tập viên tạo yêu cầu và quản trị viên chấp thuận trước khi bất kỳ thay đổi nào được đưa vào. Việc hợp nhất chỉ chọn các tài nguyên bạn chỉ định, vì vậy một thay đổi được chia sẻ vẫn nằm trong phạm vi.
# Propose the change for review (safe against a protected main)
apidog merge-request create --branch "orders-pagination" --endpoint-ids 1,2
Và git-connection sao lưu tệp OpenAPI của mỗi mô-đun vào một kho lưu trữ Git (GitHub, GitLab hoặc Azure DevOps được hỗ trợ), vì vậy đặc tả có một bản sao trong kiểm soát phiên bản cùng với mã của bạn.
# Wire the project's specs to a Git repo for backup + history
apidog git-connection --help
Đầu ra là JSON có cấu trúc với agentHints.nextSteps, điều này giúp CLI dễ dàng điều khiển từ các tập lệnh hoặc một tác nhân AI. Để tham khảo đầy đủ các lệnh, hãy xem hướng dẫn đầy đủ về Apidog CLI.
Tốt nhất ở: một quy trình phiên bản + xem xét + hợp nhất tích hợp mà không cần lắp ráp các công cụ riêng biệt, cộng với các mô hình nhánh được xây dựng cho cả nhóm và tác nhân.
Hạn chế thực tế: nó là một CLI nền tảng, vì vậy nó là bản cài đặt nặng nhất ở đây và nó giao tiếp với dự án Apidog của bạn thay vì một tệp cục bộ đơn thuần. Nó cũng không có trình kiểm tra cú pháp OpenAPI (linter); hãy sử dụng Redocly hoặc Spectral cho các quy tắc kiểu. Khi nhóm của bạn cần quyền truy cập dựa trên vai trò ngoài các nhánh, hãy đọc thêm về cộng tác API an toàn với RBAC.
Cách chọn
Chọn công cụ phù hợp với công việc cộng tác, không phải ngược lại.
| Công cụ | Tốt nhất cho | Cài đặt | Mã nguồn mở? | Ghi chú |
|---|---|---|---|---|
| Git + tệp đặc tả | Lịch sử và xem xét, không cần công cụ mới | đã cài đặt | có (Git) | Ồn ào trên YAML; kết hợp với một công cụ so sánh ngữ nghĩa |
| oasdiff | Cổng hợp nhất cho thay đổi gây lỗi | brew install oasdiff |
có (Apache 2.0) | Mã thoát làm CI thất bại khi có lỗi |
| Optic | Xem xét thay đổi có cấu trúc trong PR | npm i -g @useoptic/optic |
có (MIT) | Hiểu $ref, oneOf, v.v. |
| Bump.sh CLI | Xuất bản tài liệu chia sẻ + so sánh | npm i -g bump-cli |
CLI mở, hosting trả phí | Node 20+; diff/preview không cần token |
| Redocly CLI | Kiểm tra cú pháp, đóng gói, đẩy lên registry | npx @redocly/cli |
CLI mở, registry trả phí | push cần khóa API |
| GitHub CLI | Điều khiển xem xét PR từ shell | brew install gh |
có (MIT) | Quản lý PR, không phải ngữ nghĩa API |
| Apidog CLI | Tích hợp phiên bản + xem xét + hợp nhất | npm i -g apidog-cli |
không (gói miễn phí) | branch / merge-request / git-connection |
Hầu hết các nhóm đều kết hợp một vài công cụ. Một bộ công cụ nhẹ phổ biến: cam kết đặc tả vào Git, chạy oasdiff hoặc Optic làm cổng hợp nhất, và xuất bản bằng Bump.sh hoặc Redocly. Nếu bạn muốn chạy phân nhánh, xem xét và hợp nhất từ một CLI duy nhất, Apidog bao gồm cả ba. Để có cái nhìn rộng hơn về việc chọn một bộ công cụ, hướng dẫn về các công cụ cộng tác API của nhóm của chúng tôi so sánh các lựa chọn.
Tóm tắt
Cộng tác từ terminal gồm ba bước: tạo phiên bản đặc tả, xem xét sự khác biệt, hợp nhất thay đổi được chia sẻ. Git xử lý bước đầu tiên, oasdiff và Optic làm sắc nét bước thứ hai, Bump.sh và Redocly xuất bản kết quả, và gh điều khiển PR. Apidog CLI tích hợp việc tạo phiên bản, xem xét và hợp nhất vào một bộ lệnh duy nhất với các mô hình nhánh được xây dựng cho cả nhóm và tác nhân.
Bạn muốn một lộ trình tích hợp mà không cần ghép nối các công cụ lại với nhau? Tải xuống Apidog, cài đặt apidog-cli, và chạy apidog branch create và merge-request đầu tiên của bạn từ terminal bạn đang làm việc. Việc kết nối CLI vào CI là một bước tiếp theo ngắn gọn từ đó.