DEV Community

Cover image for Các công cụ CLI gọn nhẹ tốt nhất cho cộng tác API
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Các công cụ CLI gọn nhẹ tốt nhất cho cộng tác API

Cộng tác API trước đây thường đồng nghĩa với việc mở một ứng dụng nặng, chờ đồng bộ hóa rồi nhấp qua nhiều bảng điều khiển để biết đồng đội đã thay đổi gì. Nhưng nếu API được mô tả bằng tệp OpenAPI, phần lớn công việc cộng tác thực chất là xử lý văn bản: tạo phiên bản đặc tả, xem xét khác biệt và hợp nhất thay đổi. Tất cả đều có thể thực hiện ngay trong terminal.

Dùng thử Apidog ngay hôm nay

Hướng dẫn này tập trung vào các CLI nhẹ cho ba việc trên. Mỗi công cụ đều có thể cài đặt nhanh, chạy bằng một lệnh và tích hợp với Git hoặc CI. Không cần GUI, không cần dịch vụ nền, không cần cấp tài khoản cho cả nhóm chỉ để xem lịch sử thay đổi. Nếu cần cái nhìn tổng quan hơn, hãy xem các công cụ cộng tác API; bài viết này chỉ tập trung vào quy trình ưu tiên terminal.

Quy trình cộng tác API từ dòng lệnh có thể chia thành ba phần:

  1. Tạo phiên bản đặc tả: biết ai đang dùng phiên bản nào.
  2. Xem xét thay đổi: biết API thay đổi gì và có gây lỗi cho client hay không.
  3. Hợp nhất thay đổi: đưa chỉnh sửa đã được duyệt vào nguồn đáng tin cậy chung.

Các công cụ dưới đây xử lý tốt một hoặc hai phần trong quy trình này. Chúng đều đọc hoặc ghi theo tiêu chuẩn OpenAPI chính thức, vì vậy có thể kết hợp trong cùng một pipeline.

Điều gì làm CLI trở nên “nhẹ” cho cộng tác API?

Một CLI phù hợp cho cộng tác API thường đáp ứng phần lớn các tiêu chí sau:

  • Cài đặt nhỏ: một binary, một lệnh npx hoặc npm install -g.
  • Khởi động nhanh: chạy xong và thoát, phù hợp cho script, Git hook và CI.
  • Ít cấu hình: chỉ cần trỏ tới openapi.yaml là có thể chạy.
  • Ưu tiên terminal: đầu ra dễ đọc trong shell hoặc dễ đưa vào pipeline CI.
  • Một nhiệm vụ rõ ràng: so sánh, lint, xuất bản hoặc hợp nhất — không buộc nhóm phải áp dụng cả một nền tảng.

Các công cụ được sắp xếp từ đơn giản, tập trung đến tích hợp hơn. Riêng Apidog CLI là một CLI cấp dự án đầy đủ, vì nó bao phủ tạo phiên bản, xem xét và hợp nhất trong cùng một nơi.

1. Git + tệp đặc tả OpenAPI

Công cụ nhẹ nhất thường là công cụ bạn đã có: Git.

Đặt openapi.yaml cạnh mã nguồn, commit nó như mọi tệp khác, và dùng pull request để xem xét thay đổi. Đây là nền tảng của cộng tác API Git-native.

# Theo dõi đặc tả trong repository
git add openapi.yaml
git commit -m "Add pagination params to GET /orders"

# Xem khác biệt của đặc tả so với main
git diff main -- openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Cách áp dụng

  1. Lưu đặc tả tại một vị trí cố định, ví dụ api/openapi.yaml.
  2. Yêu cầu mọi thay đổi API phải đi qua pull request.
  3. Đặt reviewer cho các thay đổi trong tệp OpenAPI.
  4. Kết hợp thêm semantic diff như oasdiff hoặc Optic để tránh review YAML thuần túy.

Tốt nhất cho: lịch sử thay đổi và review mà không cần thêm công cụ mới.

Hạn chế: diff Git trên YAML có thể nhiễu. Việc đổi thứ tự khóa hoặc thụt lề lại có thể trông như thay đổi API, dù ngữ nghĩa không đổi.

2. oasdiff

oasdiff là binary Go dùng để so sánh hai đặc tả OpenAPI và phát hiện breaking change. Nó là mã nguồn mở theo giấy phép Apache 2.0, hỗ trợ nhiều loại thay đổi và có exit code phù hợp cho CI.

# Cài đặt trên macOS
brew install oasdiff

# Thất bại nếu đặc tả mới phá vỡ client hiện có
oasdiff breaking main-spec.yaml pr-spec.yaml

# exit 0: không có breaking change
# exit 1: phát hiện breaking change
Enter fullscreen mode Exit fullscreen mode

Để tạo changelog của mọi thay đổi, kể cả thay đổi không gây lỗi:

oasdiff changelog base.yaml revision.yaml
Enter fullscreen mode Exit fullscreen mode

Dùng trong CI

Ví dụ GitHub Actions tối giản:

name: OpenAPI breaking-change check

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  oasdiff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install oasdiff
        run: |
          brew install oasdiff

      - name: Check breaking changes
        run: |
          git show origin/main:openapi.yaml > main-spec.yaml
          oasdiff breaking main-spec.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Tốt nhất cho: làm cổng hợp nhất để chặn breaking change.

Hạn chế: oasdiff chỉ so sánh và báo cáo. Nó không quản lý nhánh, không xuất bản tài liệu và không thay thế quy trình review.

3. Optic

Optic là CLI cài qua npm để so sánh, lint và review thay đổi OpenAPI theo quy trình Git. Công cụ được cấp phép MIT và hiểu các cấu trúc như $ref, oneOf và allOf.

# Cài đặt
npm install -g @useoptic/optic

# So sánh đặc tả hiện tại với nhánh main
optic diff openapi.yaml --base main --check
Enter fullscreen mode Exit fullscreen mode

Khi nào nên dùng Optic?

Dùng Optic khi nhóm cần review thay đổi API ở cấp độ ngữ nghĩa thay vì đọc diff YAML. Ví dụ, trong PR, bạn có thể kiểm tra xem:

  • endpoint nào được thêm hoặc xóa;
  • tham số nào đổi từ optional sang required;
  • schema response thay đổi ra sao;
  • thay đổi nào bị xem là bị cấm hoặc gây lỗi.

Tốt nhất cho: review thay đổi có cấu trúc trong pull request.

Hạn chế: phụ thuộc Node.js nên nặng hơn binary Go đơn lẻ. Để tận dụng tốt, nhóm cần duy trì cấu hình và rule kiểm tra.

4. Bump.sh CLI

Bump.sh CLI dùng để xuất bản và so sánh tài liệu API từ terminal. Mô hình cộng tác ở đây là một bộ tài liệu chia sẻ luôn đồng bộ với đặc tả.

# Cài đặt
npm install -g bump-cli

# Xuất bản phiên bản tài liệu mới
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN

# So sánh tệp cục bộ với phiên bản đã xuất bản
bump diff openapi.yaml --doc my-api
Enter fullscreen mode Exit fullscreen mode

Lệnh diff hữu ích khi bạn muốn đưa changelog vào mô tả hoặc bình luận của PR.

bump diff openapi.yaml --doc my-api > api-changelog.md
Enter fullscreen mode Exit fullscreen mode

Tốt nhất cho: xuất bản tài liệu API chung và xem changelog ngay trong terminal.

Hạn chế: tài liệu được host và quy trình deploy là một phần của sản phẩm trả phí từ Bump.sh. CLI là client; phần tài liệu dùng chung nằm trên nền tảng của họ. CLI yêu cầu Node 20+, trong khi preview và diff không yêu cầu token.

5. Redocly CLI

Redocly CLI cung cấp bộ công cụ rộng hơn cho OpenAPI: lint, bundle và push đặc tả lên registry Redocly, hiện thuộc Reunite.

# Chạy trực tiếp qua npx, không cần cài global
npx @redocly/cli lint openapi.yaml

# Gộp đặc tả đa tệp và các $ref thành một artifact
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Nếu đặc tả của bạn được chia thành nhiều tệp:

# openapi.yaml
paths:
  /orders:
    $ref: "./paths/orders.yaml"
Enter fullscreen mode Exit fullscreen mode

Hãy bundle trước khi chia sẻ hoặc xuất bản:

npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Sau đó có thể đẩy phiên bản lên registry chung:

npx @redocly/cli push openapi.yaml \
  --organization "Acme" \
  --project "orders-api"
Enter fullscreen mode Exit fullscreen mode

Pipeline thực tế 

# 1. Kiểm tra lỗi đặc tả
npx @redocly/cli lint openapi.yaml

# 2. Bundle các file $ref
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml

# 3. Chỉ push khi lint và bundle thành công
npx @redocly/cli push dist/openapi.yaml \
  --organization "Acme" \
  --project "orders-api"
Enter fullscreen mode Exit fullscreen mode

Tốt nhất cho: lint theo quy tắc chung, bundle đặc tả nhiều tệp và đẩy artifact chuẩn lên registry.

Hạn chế: lint và bundle chạy cục bộ miễn phí, nhưng push và registry là một phần của nền tảng lưu trữ Redocly. Nếu cần quy trình chỉnh sửa đặc tả sâu hơn, xem chỉnh sửa đặc tả API cộng tác.

6. GitHub CLI (gh)

Nếu nhóm review qua pull request, GitHub CLI giúp đưa quy trình đó vào terminal. Bạn có thể tạo PR, yêu cầu reviewer, kiểm tra trạng thái và merge mà không cần mở trình duyệt.

# Tạo PR cho thay đổi đặc tả
gh pr create \
  --title "Add /orders pagination" \
  --body "Adds page + limit params"

# Phê duyệt PR
gh pr review --approve
Enter fullscreen mode Exit fullscreen mode

Kết hợp với semantic diff

gh không hiểu ngữ nghĩa API. Vì vậy, hãy để oasdiff hoặc Optic chạy trong CI, sau đó dùng gh để quản lý cuộc thảo luận và merge.

# Xem trạng thái kiểm tra của PR hiện tại
gh pr checks
Enter fullscreen mode Exit fullscreen mode

Tốt nhất cho: điều phối review và hợp nhất từ shell khi đội ngũ đã dùng GitHub.

Hạn chế: chỉ quản lý PR, không phát hiện breaking change. Hãy kết hợp với oasdiff hoặc Optic.

7. Apidog CLI

Apidog CLI là ngoại lệ trong danh sách này: đây không phải CLI đơn mục đích mà là CLI cấp tài nguyên dự án. Nó truy cập dữ liệu thiết kế, phiên bản và cộng tác của dự án Apidog ngay từ terminal.

Ba nhóm lệnh quan trọng cho cộng tác là:

  • branch
  • merge-request
  • git-connection

Apidog không phải mã nguồn mở; đây là sản phẩm thương mại có gói miễn phí. Nếu không muốn tự ghép một công cụ diff, một công cụ xuất bản tài liệu và một registry, bạn có thể dùng CLI cùng workflow tích hợp của Apidog.

Tạo nhánh cho thay đổi API 

# Cài đặt và xác thực
npm install -g apidog-cli
apidog login --with-token $APIDOG_TOKEN

# Tạo sprint branch cho thay đổi chung
apidog branch create --type sprint --name "orders-pagination"
Enter fullscreen mode Exit fullscreen mode

Cờ --type chọn mô hình nhánh:

  • sprint: cho tính năng hoặc bản phát hành cụ thể;
  • general: cho công việc đang diễn ra;
  • ai: cho nhánh riêng, nơi tác nhân chỉnh sửa tài nguyên mà không đụng vào mã nguồn.

Tạo merge request thay vì merge trực tiếp

Khi nhánh chính được bảo vệ, hãy dùng merge request để tạo cổng review:

# Đề xuất thay đổi để review
apidog merge-request create \
  --branch "orders-pagination" \
  --endpoint-ids 1,2
Enter fullscreen mode Exit fullscreen mode

Lệnh này chỉ chọn các tài nguyên được chỉ định để hợp nhất, giúp giữ thay đổi trong đúng phạm vi.

Sao lưu đặc tả sang Git

git-connection kết nối tệp OpenAPI của từng module với repository Git. GitHub, GitLab và Azure DevOps được hỗ trợ.

# Xem cách cấu hình kết nối Git
apidog git-connection --help
Enter fullscreen mode Exit fullscreen mode

CLI trả về JSON có cấu trúc với agentHints.nextSteps, phù hợp để gọi từ script hoặc tác nhân AI. Xem thêm hướng dẫn đầy đủ về Apidog CLI.

Tốt nhất cho: workflow tích hợp gồm tạo phiên bản, review và merge mà không phải lắp ghép công cụ riêng lẻ.

Hạn chế: đây là CLI nền tảng nên nặng hơn các công cụ chỉ xử lý tệp cục bộ. Nó giao tiếp với dự án Apidog và không thay thế OpenAPI linter; dùng Redocly hoặc Spectral nếu cần rule về style. Nếu nhóm cần phân quyền ngoài mô hình nhánh, xem cộng tác API an toàn với RBAC.

Cách chọn công cụ

Chọn theo nhiệm vụ cộng tác cần giải quyết, không phải theo số lượng tính năng.

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à review, không thêm công cụ Đã cài đặt Có (Git) Diff YAML có thể nhiễu; nên kết hợp semantic diff
oasdiff Cổng merge cho breaking change brew install oasdiff Có (Apache 2.0) Exit code phù hợp cho CI
Optic Review thay đổi có cấu trúc trong PR npm i -g @useoptic/optic Có (MIT) Hiểu $ref, oneOf, allOf
Bump.sh CLI Xuất bản tài liệu chung và so sánh npm i -g bump-cli CLI mở, hosting trả phí Node 20+; diff và preview không cần token
Redocly CLI Lint, bundle, push lên registry npx @redocly/cli CLI mở, registry trả phí push yêu cầu API key
GitHub CLI Điều khiển review PR từ shell brew install gh Có (MIT) Quản lý PR, không hiểu ngữ nghĩa API
Apidog CLI Tích hợp phiên bản, review và merge npm i -g apidog-cli Không, có gói miễn phí branch, merge-request, git-connection

Hầu hết nhóm sẽ kết hợp nhiều công cụ. Một stack nhẹ, thực dụng có thể là:

# 1. Lint đặc tả
npx @redocly/cli lint openapi.yaml

# 2. Kiểm tra breaking change trước khi merge
oasdiff breaking main-spec.yaml openapi.yaml

# 3. Bundle artifact để chia sẻ hoặc xuất bản
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml

# 4. Mở PR từ terminal
gh pr create --title "Update OpenAPI specification"
Enter fullscreen mode Exit fullscreen mode

Nếu cần tài liệu chia sẻ, thêm Bump.sh hoặc Redocly vào bước xuất bản. Nếu muốn quản lý nhánh, review và merge từ một CLI duy nhất, Apidog bao phủ cả ba. Để so sánh rộng hơn, xem các công cụ cộng tác API cho nhóm.

Tóm tắt

Cộng tác API từ terminal gồm ba bước:

  1. Tạo phiên bản đặc tả.
  2. Review sự khác biệt.
  3. Hợp nhất thay đổi đã được duyệt.

Git xử lý lịch sử và phiên bản. oasdiff và Optic làm rõ thay đổi ở cấp độ API. Bump.sh và Redocly giúp xuất bản kết quả. GitHub CLI điều phối pull request. Apidog CLI tích hợp tạo phiên bản, review và merge vào cùng một bộ lệnh.

Nếu bạn muốn một workflow tích hợp thay vì tự ghép các công cụ, hãy tải xuống Apidog, cài apidog-cli, rồi tạo nhánh và merge request đầu tiên ngay từ terminal:


bash
apidog branch create --type sprint --name "my-api-change"
apidog merge-request create --branch "my-api-change"
Enter fullscreen mode Exit fullscreen mode

Top comments (1)

Collapse
 
topstar_ai profile image
Luis •

Tôi đồng ý rằng việc sử dụng Git để quản lý và cộng tác API là một cách tiếp cận đơn giản nhưng hiệu quả. Việc đặt tệp OpenAPI cạnh mã nguồn và sử dụng pull request để xem xét thay đổi giúp cho quá trình cộng tác trở nên minh bạch và dễ dàng theo dõi. Tuy nhiên, tôi cũng thấy rằng việc sử dụng công cụ như oasdiff có thể giúp cải thiện quá trình xem xét thay đổi bằng cách cung cấp thông tin chi tiết hơn về các breaking change. Tôi đang sử dụng oasdiff trong dự án của mình và thấy rằng nó giúp giảm thiểu rủi ro khi thực hiện thay đổi API. Bạn có kinh nghiệm gì khi sử dụng oasdiff hoặc các công cụ tương tự không?