DEV Community

Cover image for Công cụ CLI mã nguồn mở miễn phí cho thiết kế API
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Công cụ CLI mã nguồn mở miễn phí cho thiết kế API

Thiết kế API bắt đầu từ tệp đặc tả, rất lâu trước khi bất kỳ đoạn mã nào được triển khai. Một quy tắc kiểu bị bỏ sót, một thay đổi gây lỗi không được phát hiện, hoặc một schema lệch khỏi bản triển khai tuần trước đều sẽ tốn chi phí sửa chữa cao hơn khi đã lên production. CLI giúp phát hiện các vấn đề này sớm và tự động chạy chúng trong CI mà không cần thao tác qua giao diện.

Dùng thử Apidog ngay hôm nay

Bài viết này tập trung vào bộ công cụ mã nguồn mở cho thiết kế API. Các công cụ bên dưới đều có mã nguồn công khai, dùng miễn phí không giới hạn người dùng, có thể ghim phiên bản và chạy trong môi trường tự lưu trữ hoặc CI cô lập mạng. Điều này đặc biệt hữu ích khi đặc tả API được quản lý trong Git và bạn cần cùng một bộ kiểm tra chạy nhất quán trên máy local lẫn pipeline.

Nếu cần bức tranh tổng quan trước, hãy xem hướng dẫn về cách thiết kế API. Sau đó, bạn có thể chọn CLI phù hợp từ danh sách này.

Bạn sẽ có sáu công cụ chính:

  • Linter để thực thi quy tắc kiểu API.
  • Linter viết bằng Go để chạy nhanh hơn.
  • Bundler kiêm công cụ xác thực.
  • Công cụ sinh SDK, server stub và tài liệu.
  • Hai công cụ so sánh phiên bản để phát hiện thay đổi gây lỗi.

Tất cả đều sử dụng đặc tả OpenAPI, vì vậy đầu ra của công cụ này có thể chuyển trực tiếp sang công cụ tiếp theo.

Lưu ý về Apidog: Apidog được đề cập như một công cụ bổ sung, không phải công cụ mã nguồn mở. Đây là sản phẩm thương mại có gói miễn phí và không thay thế linter OpenAPI. Các công cụ mã nguồn mở thực sự là Spectral, vacuum, Redocly CLI, openapi-generator, oasdiff và Optic.

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

“Mã nguồn mở” không chỉ là có repository công khai. Với danh sách này, một công cụ cần đáp ứng ba tiêu chí.

1. Có giấy phép sử dụng rõ ràng

Công cụ cần dùng giấy phép tự do hoặc copyleft thực sự, chẳng hạn MIT hoặc Apache-2.0. Điều này cho phép bạn sử dụng trong dự án thương mại mà không trả phí giấy phép hoặc bị giới hạn số lượng người dùng.

2. Có thể tự lưu trữ và kiểm soát phiên bản

Bạn cần có khả năng:

  • Ghim chính xác phiên bản CLI.
  • Đóng gói binary hoặc dependency trong pipeline.
  • Chạy hoàn toàn offline trên air-gapped CI runner.
  • Không cần tài khoản hoặc gửi đặc tả API lên máy chủ bên thứ ba để chạy chức năng cốt lõi.

3. Có tín hiệu bảo trì rõ ràng

Ưu tiên dự án có:

  • Commit gần đây.
  • Issue được phản hồi.
  • Changelog công khai.
  • Bản phát hành được duy trì.

Một dự án vẫn có giấy phép MIT nhưng bị bỏ rơi có thể trở thành rủi ro trong pipeline dài hạn. Phần Optic bên dưới là ví dụ cần lưu ý.

Spectral: linter OpenAPI linh hoạt cho quy tắc kiểu

Spectral của Stoplight là linter mã nguồn mở phổ biến cho đặc tả API, được cấp phép Apache-2.0. Nó đọc rule set YAML, JSON hoặc JavaScript và áp dụng quy tắc lên OpenAPI 3.x, OpenAPI 2.0, AsyncAPI và Arazzo.

Cài đặt và chạy nhanh:

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

Bắt đầu với rule set mặc định oas:

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

Giá trị chính của Spectral nằm ở rule tùy chỉnh. Ví dụ, tạo file .spectral.yaml để yêu cầu mọi operation có operationId:

extends:
  - spectral:oas

rules:
  require-operation-id:
    description: "Mọi operation phải có operationId"
    given: $.paths[*][get,post,put,patch,delete,head,options,trace]
    then:
      field: operationId
      function: truthy
Enter fullscreen mode Exit fullscreen mode

Chạy linter với rule set của repository:

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

Bạn có thể tiếp tục bổ sung quy tắc cho:

  • Schema phản hồi lỗi dùng chung.
  • Quy ước đặt tên path.
  • Mô tả bắt buộc cho operation.
  • Ví dụ request/response.
  • Quy tắc phân trang hoặc versioning.

Phù hợp nhất cho: biến API style guide của nhóm thành quy tắc thực thi được.

Hạn chế: Spectral kiểm tra một đặc tả tại một thời điểm, không so sánh hai phiên bản. Dùng thêm oasdiff để phát hiện thay đổi gây lỗi.

vacuum: linter Go tốc độ cao, tương thích rule Spectral

Nếu Spectral là tiêu chuẩn phổ biến, vacuum là lựa chọn phù hợp khi cần tốc độ. Đây là linter viết bằng Go, cấp phép MIT, tương thích với rule set Spectral.

Cài đặt và chạy:

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Cờ -d hiển thị đầu ra chi tiết theo từng quy tắc.

Bạn có thể dùng chính rule set Spectral hiện có:

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

Vì là binary được biên dịch sẵn và không cần Node runtime, vacuum phù hợp cho:

  • Git pre-commit hook.
  • CI pipeline cần phản hồi nhanh.
  • Container tối giản.
  • Đặc tả OpenAPI lớn hoặc nhiều file.

vacuum cũng có thể tạo báo cáo HTML và tài liệu từ đặc tả.

Phù hợp nhất cho: lint nhanh các đặc tả lớn bằng rule set Spectral hiện có.

Hạn chế: hệ sinh thái tài liệu và rule set vẫn tập trung chủ yếu vào Spectral. Thông thường, nhóm sẽ học cách viết rule Spectral trước rồi chạy chúng bằng vacuum.

Redocly CLI: lint, bundle và chuẩn bị đặc tả cho CI

Redocly CLI được cấp phép MIT. Điểm mạnh nhất của nó là bundle: gom đặc tả OpenAPI được chia thành nhiều tệp $ref thành một tài liệu duy nhất.

Cài đặt:

npm install -g @redocly/cli
Enter fullscreen mode Exit fullscreen mode

Lint đặc tả:

redocly lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Bundle đặc tả đa tệp:

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

Ví dụ cấu trúc repository phù hợp với Redocly:

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── components/
    ├── schemas/
    │   ├── User.yaml
    │   └── Error.yaml
    └── responses/
        └── NotFound.yaml
Enter fullscreen mode Exit fullscreen mode

Sau khi bundle, các công cụ downstream có thể dùng một file duy nhất:

redocly bundle openapi/openapi.yaml -o dist/openapi.yaml
spectral lint dist/openapi.yaml --ruleset .spectral.yaml
Enter fullscreen mode Exit fullscreen mode

Việc chia đặc tả theo resource giúp diff Git dễ đọc hơn và giảm xung đột merge. Đây là một phần quan trọng của quy trình thiết kế API gốc Git.

Phù hợp nhất cho: dự án OpenAPI đa tệp cần bundle và xác thực.

Hạn chế: rule lint mặc định nhẹ hơn một rule set Spectral tùy chỉnh đầy đủ. Nhiều nhóm dùng Redocly để bundle và dùng Spectral hoặc vacuum để thực thi style guide.

openapi-generator: sinh SDK, server stub và tài liệu từ OpenAPI

Thiết kế API chỉ thực sự hữu ích khi các nhóm khác có thể xây dựng dựa trên nó. openapi-generator là công cụ Apache-2.0 có thể sinh SDK client, server stub và tài liệu từ OpenAPI trên nhiều ngôn ngữ.

Cài đặt:

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

Sinh TypeScript client sử dụng Axios:

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

Thay typescript-axios bằng generator phù hợp:

# 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 client
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java

# Kotlin client
openapi-generator-cli generate -i openapi.yaml -g kotlin -o ./client-kotlin
Enter fullscreen mode Exit fullscreen mode

Một cách triển khai thực tế là sinh code trong CI và kiểm tra xem output có bị thay đổi không:

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

git diff --exit-code -- ./generated/client
Enter fullscreen mode Exit fullscreen mode

Nếu đặc tả thay đổi nhưng SDK chưa được cập nhật, bước CI này sẽ thất bại.

Cách làm này giữ đặc tả làm nguồn đáng tin cậy duy nhất, phù hợp với hướng tiếp cận schema-first và contract-first được đề cập trong các nguyên tắc thiết kế API.

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

Hạn chế: cần JDK 11+, code sinh ra thường cần tùy chỉnh, và chất lượng generator khác nhau theo ngôn ngữ đích. Luôn kiểm tra output trước khi đưa vào production.

oasdiff: chặn thay đổi gây lỗi trước khi đến client

Linter có thể cho biết đặc tả có đúng cấu trúc hay không, nhưng không thể phát hiện việc xóa một field bắt buộc hoặc đổi kiểu dữ liệu làm hỏng client hiện tại.

oasdiff là công cụ Go, cấp phép Apache-2.0, dùng để so sánh hai phiên bản OpenAPI và phát hiện các thay đổi gây lỗi.

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 quan trọng:

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

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

# Xuất toàn bộ khác biệt có thể xử lý bằng máy
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Ví dụ trong pull request: so sánh nhánh hiện tại với đặc tả trên nhánh chính.

git show origin/main:openapi.yaml > /tmp/openapi-main.yaml

oasdiff breaking /tmp/openapi-main.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Nếu lệnh trả về lỗi vì có breaking change, CI có thể chặn merge cho đến khi nhóm:

  • Tạo API version mới.
  • Thêm field mới thay vì đổi field cũ.
  • Giữ endpoint cũ trong thời gian deprecation.
  • Cập nhật client theo kế hoạch migration rõ ràng.

Phù hợp nhất cho: ngăn thay đổi gây lỗi trong CI và pull request.

Hạn chế: oasdiff chỉ tốt khi OpenAPI luôn phản ánh API thật. Nó không thay thế linter style guide, vì vậy nên dùng cùng Spectral hoặc vacuum.

Optic: lint và diff trong một CLI, nhưng cần lưu ý bảo trì

Optic được cấp phép MIT. Nó kết hợp lint và diff OpenAPI: so sánh hai phiên bản để đánh dấu thay đổi gây lỗi đồng thời kiểm tra quy tắc kiểu. Optic cũng có thể tạo đặc tả từ lưu lượng kiểm thử đã quan sát.

Cài đặt và chạy:

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

Tuy nhiên, có một điểm quan trọng: repository công khai của Optic đã được lưu trữ từ đầu năm 2026 và dự án không còn được duy trì tích cực.

Mã nguồn MIT vẫn có thể chạy và bạn vẫn có thể đóng gói nó trong pipeline hiện có. Nhưng bạn không nên kỳ vọng:

  • Rule mới.
  • Bản vá bảo mật.
  • Cập nhật tương thích dài hạn.
  • Hỗ trợ cho các thay đổi mới trong hệ sinh thái OpenAPI.

Nếu đang dùng Optic, hãy lên kế hoạch chuyển dần sang:

  • Spectral hoặc vacuum cho lint.
  • oasdiff cho breaking-change detection.

Phù hợp nhất cho: nhóm đã đầu tư vào Optic hoặc cần lint và diff trong một CLI.

Hạn chế: không còn được duy trì từ đầu năm 2026; nên xem đây là công cụ legacy.

Apidog phù hợp ở đâu và không phù hợp ở đâu?

Apidog không phải là mã nguồn mở và không phải linter OpenAPI. Nếu cần thực thi rule style, hãy dùng Spectral, vacuum hoặc Redocly CLI.

Điểm mạnh của Apidog là tập trung thiết kế endpoint và schema vào một nơi, sau đó xuất OpenAPI để đưa trở lại pipeline mã nguồn mở.

Cài đặt CLI:

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

Đăng nhập và làm việc với API:

apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Sau khi xuất, tiếp tục dùng các CLI mã nguồn mở:

# Lint
spectral lint openapi.yaml --ruleset .spectral.yaml

# Bundle nếu cần
redocly bundle openapi.yaml -o dist/openapi.yaml

# Phát hiện breaking changes
oasdiff breaking old-openapi.yaml dist/openapi.yaml

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

Apidog CLI có các nhóm lệnh như endpoint, schema, mock và import/export. Xem hướng dẫn đầy đủ về Apidog CLI để biết toàn bộ bộ lệnh.

Khung sử dụng thực tế:

  • Apidog: thiết kế tích hợp và xuất OpenAPI.
  • Spectral/vacuum: kiểm tra style guide.
  • Redocly: bundle đặc tả đa tệp.
  • oasdiff: phát hiện breaking changes.
  • openapi-generator: sinh client hoặc server stub.

Cách chọn công cụ

Hầu hết các nhóm không chỉ dùng một công cụ. Hãy ghép công cụ theo từng bước trong workflow.

Công cụ Tốt nhất cho Cài đặt Mã nguồn mở? Ghi chú
Spectral Kiểm tra cú pháp theo style guide npm i -g @stoplight/spectral-cli Có (Apache-2.0) Linter tham chiếu; hỗ trợ rule tùy chỉnh
vacuum Lint nhanh ở quy mô lớn brew install --cask daveshanley/vacuum/vacuum Có (MIT) Chạy rule Spectral với tốc độ Go
Redocly CLI Bundle + xác thực npm i -g @redocly/cli Có (MIT) Phù hợp với đặc tả $ref đa tệp
openapi-generator Sinh SDK, stub, tài liệu npm i -g @openapitools/openapi-generator-cli Có (Apache-2.0) Cần JDK 11+
oasdiff Phát hiện breaking changes go install github.com/oasdiff/oasdiff@latest Có (Apache-2.0) Được duy trì; nên chạy trong kiểm tra PR
Optic Lint + diff trong một công cụ npm i -g @useoptic/optic Có (MIT) Repository đã archived từ đầu năm 2026
Apidog CLI Thiết kế tích hợp + xuất npm i -g apidog-cli Không (gói miễn phí) Không thay thế linter; xuất OpenAPI

Stack đề xuất cho hầu hết dự án

Một pipeline thực tế có thể gồm:

  1. Spectral hoặc vacuum để kiểm tra style guide.
  2. Redocly CLI để bundle đặc tả đa tệp.
  3. oasdiff để chặn breaking changes.
  4. openapi-generator để tạo SDK hoặc stub.

Ví dụ pipeline shell:

#!/usr/bin/env bash
set -euo pipefail

# 1. Lint source specification
spectral lint openapi/openapi.yaml --ruleset .spectral.yaml

# 2. Bundle all $ref files
redocly bundle openapi/openapi.yaml -o dist/openapi.yaml

# 3. Check compatibility with the main branch
git show origin/main:dist/openapi.yaml > /tmp/openapi-main.yaml || true

if [ -s /tmp/openapi-main.yaml ]; then
  oasdiff breaking /tmp/openapi-main.yaml dist/openapi.yaml
fi

# 4. Generate a client from the validated contract
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o generated/client
Enter fullscreen mode Exit fullscreen mode

Nếu bạn cần một công cụ tích hợp cho giai đoạn thiết kế và xuất, hãy kết hợp nó với pipeline trên thay vì thay thế các bước kiểm tra. Để xem thêm công cụ ngoài CLI, hãy đọc về các lựa chọn thay thế Swagger cho thiết kế và kiểm thử API và cách thiết kế API REST.

Tổng kết

Bộ CLI mã nguồn mở cho thiết kế API đã đủ trưởng thành để đưa trực tiếp vào workflow hằng ngày:

  • Spectral và vacuum kiểm tra quy tắc kiểu.
  • Redocly CLI bundle đặc tả.
  • openapi-generator sinh SDK, stub và tài liệu.
  • oasdiff bảo vệ client khỏi breaking changes.
  • Optic là lựa chọn legacy cần cân nhắc khi gặp trong pipeline cũ.

Khi tích hợp các công cụ này vào CI, hợp đồng API được kiểm tra trên mọi lần push, không phụ thuộc vào số lượng người dùng và không bị khóa vào một nhà cung cấp.

Nếu muốn thiết kế endpoint và schema trong một công cụ tích hợp rồi xuất OpenAPI vào cùng pipeline, hãy tải xuống Apidog và thử apidog-cli. Đây là công cụ thương mại bổ sung cho stack mã nguồn mở, không phải thay thế cho linter của bạn.

Mục tiêu cuối cùng vẫn giống nhau: phát hiện vấn đề thiết kế trong terminal trước khi chúng ảnh hưởng đến người dùng.

Top comments (0)