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

Thiết kế API diễn ra trong tệp đặc tả của bạn 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 mà bạn quên, một thay đổi gây lỗi mà bạn bỏ lỡ, một schema lệch khỏi những gì bạn đã triển khai tuần trước; tất cả đều tốn nhiều chi phí hơn để khắc phục sau khi sự việc đã xảy ra. Dòng lệnh bắt những vấn đề này ngay từ khi chúng bắt đầu và thực hiện điều đó trong CI mà không cần bất kỳ ai phải nhấp chuột qua giao diện người dùng.

Bài viết này nói về khía cạnh mã nguồn mở của bộ công cụ đó. Mọi công cụ ở đây đều có sẵn mã nguồn theo giấy phép tùy ý, miễn phí sử dụng không giới hạn số lượng người dùng, và bạn có thể tự lưu trữ hoặc ghim vào một phiên bản bạn kiểm soát. Điều đó quan trọng khi thiết kế API của bạn nằm trong một kho Git và bạn muốn các kiểm tra chạy theo cùng một cách trên mọi máy tính xách tay và mọi pipeline. Nếu bạn muốn có cái nhìn tổng quan hơn về cách chúng kết hợp với nhau, hãy bắt đầu với hướng dẫn của chúng tôi về cách thiết kế API, sau đó quay lại đây để chọn các công cụ dòng lệnh (CLI).

Bạn sẽ nhận được sáu công cụ, mỗi công cụ đều có lệnh cài đặt thực tế và một lệnh duy nhất để minh họa cách nó hoạt động: một công cụ kiểm tra cú pháp (linter) cho các quy tắc kiểu, một giải pháp thay thế nhanh chóng dựa trên Go, một công cụ đóng gói (bundler) cũng có chức năng xác thực, một công cụ tạo mã và tài liệu, và hai công cụ để phát hiện các thay đổi gây lỗi giữa các phiên bản đặc tả. Thông số kỹ thuật OpenAPI là ngôn ngữ chung mà tất cả các công cụ này sử dụng, vì vậy một đặc tả mà bạn kiểm tra bằng một công cụ sẽ được đưa một cách liền mạch vào công cụ tiếp theo.

Một lưu ý thẳng thắn ngay từ đầu. Apidog được giới thiệu ở đây, nhưng nó không phải là mã nguồn mở; nó là một sản phẩm thương mại với gói miễn phí và nó không kiểm tra cú pháp đặc tả của bạn. Vì vậy, nó được đề cập như một phần phụ chính xác, chứ không phải là một mục mã nguồn mở. Các công cụ dưới đây là bộ công cụ thiết kế mã nguồn mở thực sự.

Điều gì làm cho một công cụ CLI trở thành mã nguồn mở cho thiết kế API

Mã nguồn mở là một khẳng định cụ thể, không phải là một cảm giác chung chung. Đối với danh sách này, một công cụ được coi là đủ điều kiện khi ba điều sau đây là đúng.

Thứ nhất, giấy phép. Nó phải là một giấy phép tự do (permissive) hoặc copyleft thực sự mà bạn có thể đọc; MIT và Apache-2.0 là hai giấy phép bạn sẽ thấy nhiều nhất ở đây. Đó là điều cho phép bạn sử dụng công cụ này trong một dự án thương mại mà không phải trả phí giấy phép hoặc giới hạn số lượng người dùng.

Thứ hai, khả năng tự lưu trữ và kiểm soát phiên bản. Bạn có thể đóng gói nhị phân (vendor the binary), ghim một phiên bản chính xác và chạy nó hoàn toàn ngoại tuyến trong một trình chạy CI cách ly mạng (air-gapped CI runner). Không có công cụ nào ở đây gửi dữ liệu về máy chủ hoặc yêu cầu tài khoản để thực hiện công việc cốt lõi của nó.

Thứ ba, bảo trì và cộng đồng. Một kho lưu trữ với các commit gần đây, các vấn đề mở được trả lời và một nhật ký thay đổi công khai. Một dự án bị bỏ rơi vẫn có thể được cấp phép MIT và vẫn là một lựa chọn tồi, vì vậy tôi đánh dấu tình trạng bảo trì ở những nơi quan trọng.

Mọi công cụ dưới đây đều được kiểm tra dựa trên ba tiêu chí đó. Nếu một dự án đang duy trì ở mức tối thiểu, bạn sẽ thấy nó được chỉ rõ.

Spectral: công cụ kiểm tra cú pháp kiểu OpenAPI linh hoạt

Spectral từ Stoplight là công cụ kiểm tra cú pháp (linter) mã nguồn mở tham chiếu cho các mô tả API, được cấp phép theo Apache-2.0. Nó đọc một bộ quy tắc (một tệp YAML, JSON hoặc JavaScript liệt kê các quy tắc của bạn) và áp dụng chúng cho các tài liệu OpenAPI 3.x, OpenAPI 2.0, AsyncAPI và Arazzo. Nếu nhóm của bạn có một hướng dẫn về kiểu API bằng văn bản, Spectral là cách bạn biến nó thành có thể thực thi.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Ngay từ đầu, nó đi kèm với một bộ quy tắc oas để đánh dấu các mô tả bị thiếu, ví dụ không hợp lệ và các vấn đề cấu trúc. Giá trị thực sự thể hiện ở các quy tắc tùy chỉnh: yêu cầu một operationId trên mọi thao tác, một schema chung cho các phản hồi lỗi, một quy ước đặt tên trên các đường dẫn. Những quy tắc đó nằm trong kho lưu trữ của bạn và chạy giống hệt nhau cho mọi người đóng góp.

Tốt nhất ở: thực thi hướng dẫn kiểu của nhóm dưới dạng mã. Hạn chế thực tế: Spectral kiểm tra một đặc tả duy nhất; nó không so sánh hai phiên bản, vì vậy hãy kết hợp nó với một công cụ diff để phát hiện các thay đổi gây lỗi.

vacuum: công cụ kiểm tra cú pháp nhanh nhất, thay thế trực tiếp cho bộ quy tắc Spectral

Nếu Spectral là tiêu chuẩn, thì vacuum là lựa chọn về tốc độ. Đây là một công cụ kiểm tra cú pháp bằng Go, được cấp phép MIT, tương thích 100% với các bộ quy tắc của Spectral. Vì vậy, bạn có thể hướng nó đến cùng một bộ quy tắc mà bạn đã viết và nhận kết quả nhanh hơn nhiều đối với các đặc tả lớn, điều mà bạn rất cần trong một hook trước khi commit hoặc một vòng lặp CI chặt chẽ.

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml

Cờ -d cung cấp cho bạn đầu ra chi tiết theo từng quy tắc. vacuum cũng làm được nhiều hơn là chỉ kiểm tra cú pháp; nó tạo ra các báo cáo HTML và tài liệu từ cùng một đặc tả. Vì nó là một tệp nhị phân được biên dịch duy nhất không có thời gian chạy Node, nó khởi động nhanh và dễ dàng tích hợp vào một container.

Tốt nhất ở: kiểm tra cú pháp các đặc tả lớn một cách nhanh chóng với các bộ quy tắc bạn đã có. Hạn chế thực tế: hệ sinh thái bộ quy tắc và tài liệu vẫn tập trung vào Spectral, vì vậy bạn thường viết quy tắc dựa trên mô hình của Spectral và chạy chúng qua vacuum. Đó là một tính năng, nhưng nó có nghĩa là Spectral vẫn là thứ bạn học đầu tiên.

Redocly CLI: kiểm tra cú pháp cộng đóng gói trong một tệp nhị phân

Redocly CLI được cấp phép MIT và đảm nhiệm một công việc hơi khác. Nó kiểm tra cú pháp, nhưng điểm nổi bật của nó là bundle: nó lấy một đặc tả được chia thành nhiều tệp $ref (cách hợp lý để duy trì thiết kế API lớn) và làm phẳng nó thành một tài liệu duy nhất cho các công cụ yêu cầu một tệp. Nó cũng tạo tài liệu tham chiếu API từ kết quả đóng gói.

npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml

Chia đặc tả của bạn thành các tệp theo từng tài nguyên giúp các bản diff dễ đọc và giảm thiểu xung đột hợp nhất, điều này là cốt lõi cho một quy trình thiết kế API gốc Git. Chức năng bundle của Redocly là bước biến nguồn đa tệp đó trở lại thành một thành phẩm duy nhất mà CI, máy chủ giả lập hoặc trang tài liệu của bạn sử dụng.

Tốt nhất ở: các dự án đặc tả đa tệp cần đóng gói cộng với một lần xác thực. Hạn chế thực tế: các quy tắc kiểm tra cú pháp mặc định của nó nhẹ hơn so với một bộ quy tắc Spectral tùy chỉnh đầy đủ, vì vậy nhiều nhóm sử dụng Redocly để đóng gói và Spectral hoặc vacuum để thực thi kiểu sâu hơn.

openapi-generator: biến thiết kế thành client, stub và tài liệu

Thiết kế chưa hoàn thành cho đến khi những người khác có thể xây dựng dựa trên nó. openapi-generator là công cụ Apache-2.0 tạo ra các SDK client, stub server và tài liệu từ một đặc tả OpenAPI trên hàng chục ngôn ngữ. Coi đặc tả là nguồn đáng tin cậy và tạo ra phần còn lại là trọng tâm của phương pháp tiếp cận ưu tiên schema, định hướng hợp đồng, mà chúng tôi đã đề cập trong các nguyên tắc thiết kế API.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

Thay thế -g typescript-axios bằng go, python, java, kotlin hoặc bất kỳ trình tạo nào trong số rất nhiều trình tạo được hỗ trợ. Chạy nó trong CI trên mỗi thay đổi đặc tả và các thư viện client của bạn sẽ không bao giờ lệch khỏi hợp đồng.

Tốt nhất ở: giữ cho mã và tài liệu được tạo ra đồng bộ với thiết kế. Hạn chế thực tế: nó cần một JDK để chạy (JDK 11+), mã được tạo ra chỉ là một điểm khởi đầu mà bạn thường xuyên tùy chỉnh, và chất lượng trình tạo thay đổi tùy theo ngôn ngữ mục tiêu. Hãy kiểm tra đầu ra trước khi bạn triển khai.

oasdiff: phát hiện các thay đổi gây lỗi trước khi chúng đến tay client

Một công cụ kiểm tra cú pháp cho bạn biết liệu một đặc tả có sạch hay không. Nó không thể cho bạn biết rằng việc đổi tên một trường vừa làm hỏng mọi client trong môi trường sản xuất. oasdiff là công cụ Go Apache-2.0 lấp đầy khoảng trống đó: cung cấp cho nó hai phiên bản của một đặc tả và nó sẽ báo cáo sự khác biệt, đặc biệt là các thay đổi gây lỗi.

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml

Lệnh breaking chỉ làm nổi bật những thay đổi gây lỗi cho các client hiện có; changelog cung cấp một danh sách dễ đọc về mọi thứ đã thay đổi, dù có gây lỗi hay không; diff cung cấp toàn bộ delta có thể đọc được bằng máy. Tích hợp oasdiff breaking vào một kiểm tra yêu cầu kéo (pull-request check) và một thay đổi gây lỗi sẽ trở thành một bản dựng thất bại thay vì một thông báo khẩn cấp lúc 3 giờ sáng.

Tốt nhất ở: ngăn chặn các thay đổi gây lỗi trong CI. Hạn chế thực tế: nó so sánh các đặc tả, vì vậy nó chỉ hiệu quả bằng mức độ kỷ luật của bạn trong việc giữ đặc tả cập nhật với API thực tế. Nó không kiểm tra cú pháp kiểu; hãy sử dụng nó cùng với Spectral hoặc vacuum.

Optic: đối chiếu và kiểm tra cú pháp cùng nhau, với một lưu ý về bảo trì

Optic được cấp phép MIT và thực hiện một điều mà các công cụ khác tách rời: nó kiểm tra cú pháp và đối chiếu (diff) OpenAPI trong một công cụ, so sánh hai phiên bản để đánh dấu các thay đổi gây lỗi đồng thời áp dụng các quy tắc kiểu. Nó thậm chí có thể tạo một đặc tả từ lưu lượng kiểm thử đã quan sát.

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check

Đây là sự thật mà một danh sách mã nguồn mở cần cho bạn biết: kho lưu trữ công khai của Optic đã được lưu trữ (archived) vào đầu năm 2026 và dự án không còn được duy trì tích cực. Mã nguồn MIT vẫn chạy, vì vậy bạn có thể đóng gói nó, nhưng bạn sẽ không nhận được các quy tắc mới hoặc bản vá bảo mật. Để phát hiện các thay đổi gây lỗi hiện nay, oasdiff là lựa chọn được duy trì; Optic vẫn nằm trong danh sách vì bạn vẫn có thể bắt gặp nó trong các pipeline hiện có.

Tốt nhất ở: các nhóm đã đầu tư vào nó, hoặc bất kỳ ai muốn kiểm tra cú pháp và đối chiếu trong một CLI duy nhất. Hạn chế thực tế: không còn được duy trì kể từ đầu năm 2026; hãy coi nó là di sản và lên kế hoạch cho một lộ trình di chuyển.

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

Apidog không phải là mã nguồn mở, và nó không kiểm tra cú pháp OpenAPI của bạn hay thực thi các quy tắc kiểu; Spectral, vacuum và Redocly mới là các công cụ kiểm tra cú pháp của bạn, chấm hết. Điều mà Apidog cung cấp là một sự đánh đổi khác: thay vì ghép nối sáu tệp nhị phân riêng biệt, gói miễn phí của nó cùng với tệp nhị phân apidog-cli cung cấp cho bạn một nơi tích hợp để thiết kế các điểm cuối và schema dữ liệu, sau đó xuất kết quả dưới dạng OpenAPI để đưa trực tiếp trở lại các kiểm tra mã nguồn mở này.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml

CLI có các nhóm lệnh cho endpoint, schema, mock và import/export, vì vậy bạn có thể tự động hóa thiết kế API từ terminal và đưa đặc tả đã xuất cho openapi-generator hoặc oasdiff. Xem hướng dẫn đầy đủ về Apidog CLI để biết toàn bộ bộ lệnh. Khung hình chân thực: Apidog là tùy chọn thương mại, tích hợp, hoạt động tốt với bộ công cụ mã nguồn mở, không phải là sự thay thế cho một công cụ kiểm tra cú pháp và bản thân nó không phải là một dự án mã nguồn mở.

Cách lựa chọn

Chọn công cụ phù hợp với công việc. Hầu hết các nhóm chạy hai hoặc ba trong số này cùng nhau, chứ không phải chỉ một.

Một ngăn xếp thực tế: Spectral hoặc vacuum cho kiểu dáng, Redocly để đóng gói, oasdiff để phát hiện các thay đổi gây lỗi, và openapi-generator để tạo client. Nếu việc duy trì nhiều công cụ như vậy là quá sức đối với bạn, một nền tảng tích hợp sẽ bao gồm phần thiết kế và xuất ở một nơi duy nhất. Để có cái nhìn rộng hơn về bối cảnh công cụ vượt ra ngoài CLI, hãy xem hướng dẫn của chúng tôi về các lựa chọn thay thế Swagger cho thiết kế và kiểm thử API và các nguyên tắc cơ bản trong cách thiết kế API REST.

Tổng kết

Bộ công cụ CLI mã nguồn mở dành cho thiết kế API đã trưởng thành và miễn phí sử dụng: Spectral và vacuum kiểm tra cú pháp, Redocly đóng gói, openapi-generator tạo client, và oasdiff bảo vệ khỏi các thay đổi gây lỗi, với Optic là một lựa chọn cũ cần lưu ý. Tích hợp chúng vào CI và hợp đồng API của bạn sẽ được kiểm tra trên mỗi lần đẩy mà không tốn chi phí cho mỗi người dùng và không bị khóa bởi nhà cung cấp.

Nếu bạn muốn thiết kế các điểm cuối và schema trong một công cụ tích hợp và xuất OpenAPI sạch vào cùng pipeline đó, hãy Tải xuống Apidog và thử apidog-cli; đây là người bạn đồng hành thương mại của bộ công cụ mã nguồn mở, không phải là sự thay thế cho công cụ kiểm tra cú pháp của bạn. Dù bằng cách nào, mục tiêu đều giống nhau: phát hiện các vấn đề thiết kế trong terminal, trước khi chúng đến tay người dùng của bạn.