DEV Community

Cover image for Các công cụ CLI nhẹ tốt nhất để thiết kế API
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Các công cụ CLI nhẹ tốt nhất để thiết kế API

Hầu hết công cụ thiết kế API có nhiều tính năng hơn nhu cầu hằng ngày của bạn. Khi chỉ cần kiểm tra quy tắc đặt tên, gom một đặc tả bị chia nhỏ, hoặc phát hiện một trường vừa đổi tên gây lỗi client, bạn không nên phải khởi động ứng dụng desktop hay cấu hình một dịch vụ. Với CLI, các tác vụ này thường chỉ cần một lệnh và có thể đưa thẳng vào CI.

Dùng thử Apidog ngay hôm nay

Bài viết này tập trung vào sáu công cụ CLI nhỏ, khởi động nhanh và làm tốt một việc: lint đặc tả, bundle nhiều tệp OpenAPI, tạo mã và tài liệu, phát hiện thay đổi gây lỗi giữa các phiên bản, và thiết kế endpoint/schema bằng Apidog CLI. Tất cả đều đọc được OpenAPI Specification, nên bạn có thể ghép chúng thành một pipeline thống nhất. Nếu cần bối cảnh về quy trình tổng thể, hãy xem cách thiết kế API.

Điều gì khiến một CLI phù hợp cho thiết kế API?

Một công cụ CLI “nhẹ” không nhất thiết có ít tính năng. Nó cần phù hợp để chạy nhanh trên máy local, trong container mới và trong pipeline CI.

Đánh giá một công cụ theo ba tiêu chí thực tế:

  1. Cài đặt nhỏ, khởi động nhanh

    Ưu tiên một binary độc lập hoặc lệnh npx không cần cài đặt toàn cục.

  2. Có kết quả ngay với cấu hình tối thiểu

    Bạn nên có thể trỏ công cụ vào openapi.yaml và nhận kết quả trước khi phải viết file cấu hình.

  3. Dễ viết script và tích hợp CI

    Công cụ cần có exit code rõ ràng, đầu ra có cấu trúc hoặc dễ grep, và không yêu cầu GUI.

Các công cụ dưới đây được sắp theo hướng dễ áp dụng trước.

Redocly CLI: lint và bundle mà không cần cài đặt

Redocly CLI phù hợp khi bạn cần kiểm tra nhanh hoặc bundle một OpenAPI nhiều tệp. Bạn có thể chạy trực tiếp qua npx, rất tiện cho CI và kiểm tra một lần.

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

Dùng lint để kiểm tra cấu trúc đặc tả. Dùng bundle khi đặc tả của bạn phân tách bằng $ref, ví dụ:

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── schemas/
    ├── User.yaml
    └── Order.yaml
Enter fullscreen mode Exit fullscreen mode

Sau khi bundle, bạn có một tệp OpenAPI duy nhất để gửi cho mock server, công cụ tạo tài liệu hoặc generator:

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

Tách đặc tả theo resource giúp diff dễ đọc hơn và giảm xung đột merge. Đây cũng là nền tảng của quy trình thiết kế API gốc Git.

Phù hợp nhất cho: bundle đặc tả đa tệp và kiểm tra nhanh mà không cần cài đặt.

Lưu ý: bộ quy tắc mặc định tương đối nhẹ; dùng Spectral khi cần thực thi style guide chi tiết.

Spectral: thực thi API style guide bằng mã

Spectral là linter mã nguồn mở cho OpenAPI, AsyncAPI và Arazzo. Nó phù hợp khi nhóm cần biến quy ước API thành các kiểm tra tự động trong repository.

Cài đặt và chạy kiểm tra mặc định:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Spectral có thể chạy ngay mà chưa cần rule file. Sau đó, thêm .spectral.yaml để thực thi các quy tắc riêng của nhóm:

extends: spectral:oas

rules:
  require-operation-id:
    description: Mỗi operation phải có operationId
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

  path-must-be-kebab-case:
    description: Path phải dùng kebab-case
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^/[a-z0-9-/{}/]+$"
Enter fullscreen mode Exit fullscreen mode

Chạy rule tùy chỉnh:

spectral lint openapi.yaml --ruleset .spectral.yaml
Enter fullscreen mode Exit fullscreen mode

Các rule này nên được commit cùng mã nguồn để mọi contributor và CI chạy cùng một chuẩn. Cách làm này biến các nguyên tắc thiết kế API thành kiểm tra có thể thực thi.

Phù hợp nhất cho: áp dụng quy ước đặt tên, schema lỗi dùng chung và style guide của nhóm.

Lưu ý: Spectral chỉ kiểm tra một đặc tả tại một thời điểm; nó không so sánh hai phiên bản để tìm breaking changes.

oasdiff: chặn breaking changes bằng một binary

Linter cho biết đặc tả có hợp lệ hay không, nhưng không cho biết việc xóa một field hoặc đổi response schema có làm hỏng client hiện tại hay không. oasdiff giải quyết bài toán này bằng cách so sánh hai phiên bản OpenAPI.

Cài đặt:

go install github.com/oasdiff/oasdiff@latest
Enter fullscreen mode Exit fullscreen mode

Kiểm tra breaking changes:

oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Các lệnh thường dùng:

# Chỉ báo thay đổi gây lỗi cho client hiện có
oasdiff breaking old-openapi.yaml new-openapi.yaml

# Tạo changelog dễ đọc
oasdiff changelog old-openapi.yaml new-openapi.yaml

# Xuất khác biệt đầy đủ
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Ví dụ tích hợp vào GitHub Actions:

- name: Check OpenAPI breaking changes
  run: |
    oasdiff breaking \
      api/openapi-main.yaml \
      api/openapi-pr.yaml
Enter fullscreen mode Exit fullscreen mode

Nếu oasdiff breaking trả về mã lỗi khác 0, pipeline có thể chặn pull request trước khi thay đổi được merge.

Phù hợp nhất cho: phát hiện và chặn breaking changes trong CI với thiết lập tối thiểu.

Lưu ý: kết quả chỉ chính xác khi OpenAPI luôn được cập nhật theo API thực tế. Hãy chạy cùng Spectral hoặc Redocly để kiểm tra chất lượng đặc tả.

Optic: lint và diff trong một CLI

Optic kết hợp lint và diff OpenAPI trong một công cụ. Lệnh cơ bản:

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

Điểm cần lưu ý: repository công khai của Optic đã được lưu trữ vào tháng 1 năm 2026 và dự án không còn được duy trì. Mã nguồn MIT vẫn có thể chạy, nhưng sẽ không có rule mới hoặc bản vá bảo mật mới.

Nếu pipeline hiện tại của bạn đang dùng Optic, hãy hiểu rõ vai trò của nó và lên kế hoạch chuyển sang công cụ được duy trì như oasdiff cho breaking-change detection.

Phù hợp nhất cho: các nhóm đã dùng Optic và muốn duy trì lint + diff trong một CLI.

Lưu ý: dự án không còn được duy trì từ đầu năm 2026; nên xem là công cụ kế thừa.

openapi-generator: tạo SDK, server stub và tài liệu

Thiết kế API chỉ thực sự hữu ích khi client và server có thể dùng nó. openapi-generator tạo SDK client, server stub và tài liệu từ OpenAPI cho nhiều ngôn ngữ.

Cài đặt wrapper CLI:

npm install -g @openapitools/openapi-generator-cli
Enter fullscreen mode Exit fullscreen mode

Tạo TypeScript client dùng Axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Đổi giá trị của -g để tạo đầu ra cho ngôn ngữ khác:

# Go client
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go

# Python client
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python

# Java server stub
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server
Enter fullscreen mode Exit fullscreen mode

Đưa generation vào CI để SDK luôn đồng bộ với hợp đồng API:

openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o generated/client
Enter fullscreen mode Exit fullscreen mode

Đây là một bước cốt lõi trong phát triển API ưu tiên thiết kế: OpenAPI là nguồn đáng tin cậy, còn client, stub và tài liệu được tạo từ nó.

Phù hợp nhất cho: giữ SDK, server stub và tài liệu đồng bộ với thiết kế.

Lưu ý: cần JDK 11 trở lên. Chất lượng generator thay đổi theo ngôn ngữ, và mã sinh ra thường cần tùy chỉnh.

Apidog CLI: thiết kế endpoint và schema từ terminal

Năm công cụ phía trên chủ yếu kiểm tra hoặc chuyển đổi OpenAPI đã có. Apidog bổ sung bước trước đó: thiết kế endpoint và data schema từ terminal, sau đó xuất sang OpenAPI.

Cài đặt CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Đăng nhập, xem endpoint/schema và xuất OpenAPI:

apidog login --with-token <YOUR_TOKEN>

apidog endpoint list
apidog schema list

apidog export --format openapi -o openapi.yaml
Enter fullscreen mode Exit fullscreen mode

CLI cung cấp các nhóm lệnh cho:

  • endpoint
  • schema
  • security-scheme
  • folder
  • mock
  • import
  • export

Ví dụ workflow đơn giản:

# Xuất đặc tả từ Apidog
apidog export --format openapi -o openapi.yaml

# Kiểm tra style guide
spectral lint openapi.yaml --ruleset .spectral.yaml

# Bundle nếu đặc tả dùng nhiều tệp
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# So sánh với phiên bản đã phát hành
oasdiff breaking previous-openapi.yaml dist/openapi.yaml

# Tạo SDK nếu kiểm tra thành công
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o generated/client
Enter fullscreen mode Exit fullscreen mode

Đầu ra của CLI là JSON có cấu trúc với agentHints.nextSteps, nên có thể dễ dàng nối vào script khác. Xem hướng dẫn Apidog CLI đầy đủ để biết toàn bộ lệnh.

Apidog không thay thế linter: Spectral và Redocly vẫn phù hợp để kiểm tra style và cấu trúc OpenAPI. Apidog cũng không phải mã nguồn mở; đây là sản phẩm thương mại có tầng miễn phí.

Phù hợp nhất cho: thiết kế endpoint và schema tập trung, sau đó xuất OpenAPI cho pipeline.

Lưu ý: không phải linter và không phải mã nguồn mở; nên dùng cùng các công cụ kiểm tra phía trên.

Cách chọn công cụ

Phần lớn nhóm không chỉ dùng một công cụ. Hãy ghép công cụ với từng bước trong workflow.

Công cụ Tốt nhất cho Cài đặt Mã nguồn mở? Lưu ý
Redocly CLI Bundle + lint nhanh npx @redocly/cli@latest Có (MIT) Không cần cài đặt; phù hợp đặc tả đa tệp
Spectral Lint theo style guide npm i -g @stoplight/spectral-cli Có (Apache-2.0) Có rule mặc định và rule tùy chỉnh
oasdiff Phát hiện breaking changes go install github.com/oasdiff/oasdiff@latest Có (Apache-2.0) Binary Go độc lập, được duy trì
Optic Lint + diff trong một npm i -g @useoptic/optic Có (MIT) Repository đã lưu trữ từ tháng 1 năm 2026
openapi-generator Tạo SDK / stub / tài liệu npm i -g @openapitools/openapi-generator-cli Có (Apache-2.0) Cần JDK 11+
Apidog CLI Thiết kế endpoint + xuất OpenAPI npm i -g apidog-cli Không (tầng miễn phí) Không phải linter

Một pipeline nhẹ và thực tế có thể là:

# 1. Thiết kế và xuất OpenAPI
apidog export --format openapi -o openapi.yaml

# 2. Kiểm tra quy ước API
spectral lint openapi.yaml --ruleset .spectral.yaml

# 3. Bundle nếu dùng $ref nhiều tệp
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# 4. Chặn breaking changes
oasdiff breaking previous-openapi.yaml dist/openapi.yaml

# 5. Tạo SDK khi cần
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o generated/client
Enter fullscreen mode Exit fullscreen mode

Để xem thêm công cụ ngoài CLI, hãy tham khảo các lựa chọn thay thế Swagger cho thiết kế và kiểm thử API và cách thiết kế REST API.

Tóm lại

Một bộ CLI tốt cho thiết kế API cần chạy nhanh, dễ script và dễ đưa vào CI:

  • Redocly CLI để bundle và lint nhanh.
  • Spectral để thực thi API style guide.
  • oasdiff để phát hiện breaking changes.
  • openapi-generator để tạo SDK, stub và tài liệu.
  • Optic chỉ nên duy trì khi bạn đã có pipeline cũ.
  • Apidog CLI để thiết kế endpoint/schema và xuất OpenAPI trước khi đưa vào các bước kiểm tra.

Hãy để OpenAPI đi qua pipeline trên mỗi lần push: lint trước, bundle khi cần, kiểm tra breaking changes, rồi mới tạo client. Không cần GUI trong vòng lặp kiểm tra.

Nếu bạn muốn thiết kế endpoint và schema tại một nơi rồi xuất OpenAPI vào pipeline này, hãy tải Apidog và thử apidog-cli. Đây là bước thiết kế tích hợp trước các kiểm tra mã nguồn mở, không phải sự thay thế cho linter.

Top comments (0)