Bạn đã mở một pull request, tài liệu đã được xây dựng thành công, và ba ngày sau, một đồng nghiệp thông báo cho bạn: máy chủ staging từ chối mọi yêu cầu vì tệp OpenAPI có một `ref` bị treo chỉ đến một đường dẫn mà bạn đã đổi tên. Thông số kỹ thuật trông có vẻ đúng trong trình soạn thảo. Nó đã được hiển thị trong Swagger UI. Nhưng thực tế nó không hợp lệ, và không có gì trong quy trình của bạn phát hiện ra điều đó trước khi nó được triển khai. Đó chính xác là công việc mà một công cụ dòng lệnh Swagger được tạo ra để làm: phát hiện các thông số kỹ thuật bị lỗi trước khi con người phát hiện ra. Cụm từ “swagger cli” thường đề cập đến `@apidevtools/swagger-cli`, một gói npm nhỏ với hai lệnh, `validate` và `bundle`, dùng để kiểm tra tài liệu OpenAPI và ghép nối các thông số kỹ thuật đa tệp thành một. Đây là một công cụ thực sự hữu ích, và hướng dẫn này sẽ chỉ cho bạn cách sử dụng nó đúng cách. Nó cũng chỉ ra giới hạn của công cụ này, bởi vì việc xác thực một thông số kỹ thuật chỉ là một nửa của việc tin tưởng một API; nửa còn lại là gửi các yêu cầu thực tế và xác nhận những gì được trả về, và đó là lúc một trình chạy như [Apidog CLI](https://apidog.com/vi/blog/apidog-cli-complete-guide) tiếp quản.
Vì vậy, đây thực sự là công việc của hai terminal. Đầu tiên, lint và bundle thông số kỹ thuật với `swagger-cli` (hoặc công cụ kế nhiệm của nó) để đảm bảo hợp đồng là đáng tin cậy. Sau đó, chạy các bài kiểm tra thực tế đối với API đang hoạt động từ dòng lệnh để bạn biết triển khai khớp với hợp đồng. Chúng tôi sẽ đề cập đến cả hai, nói rõ công cụ nào đảm nhiệm công việc nào, và cung cấp cho bạn các lệnh có thể sao chép-dán cho từng cái.
“swagger cli” thực sự đề cập đến điều gì
Không có một tệp nhị phân chính thức duy nhất nào được gọi là “swagger”. Tên này đề cập đến một vài công cụ khác nhau, và việc biết bạn muốn nói đến công cụ nào sẽ giúp tránh nhiều sự nhầm lẫn. * `@apidevtools/swagger-cli` là gói mà hầu hết mọi người muốn nói đến. Tệp nhị phân của nó là `swagger-cli`, và nó làm hai việc: xác thực tài liệu OpenAPI hoặc Swagger 2.0, và gom nhiều tệp thông số kỹ thuật thành một tệp duy nhất. Đây là trọng tâm của nửa đầu bài viết này. * `swagger-codegen` là một dự án SmartBear riêng biệt, lớn hơn nhiều, tạo ra các SDK client và server stubs từ một thông số kỹ thuật. Hoàn toàn là một công việc khác; chúng tôi sẽ đề cập đến nó ở cuối. * Swagger UI và Swagger Editor hoàn toàn không phải là CLI. Chúng hiển thị và chỉnh sửa các thông số kỹ thuật trong trình duyệt. Nếu bạn vẫn đang tìm hiểu định dạng, thì [giới thiệu về Swagger và OpenAPI](https://apidog.com/vi/blog/what-is-swagger-api) là điểm khởi đầu đúng đắn. Hướng dẫn này nói về công việc dòng lệnh: xác thực, gom, lint, và sau đó kiểm thử. Nếu bạn muốn một cái nhìn tổng quan rộng hơn về các nền tảng thiết kế và kiểm thử, thì [tổng hợp các lựa chọn thay thế Swagger](https://apidog.com/vi/blog/swagger-alternatives-api-design-testing) bao gồm khía cạnh GUI.
Cài đặt swagger-cli
Công cụ này được phân phối dưới dạng gói npm. Cài đặt nó trên toàn cục:
npm install -g @apidevtools/swagger-cli
Xác nhận nó đã được giải quyết:
swagger-cli --version
swagger-cli --help
Node.js là phụ thuộc hệ thống duy nhất. Bất kỳ máy hoặc hình ảnh CI nào đã cài đặt Node đều có thể chạy nó. Nếu bạn không muốn cài đặt nó trên toàn cục, bạn có thể gọi nó theo yêu cầu với `npx @apidevtools/swagger-cli ...`, rất tiện lợi trên các trình chạy build tạm thời. Một điều cần biết trước khi bạn dựa vào nó: các nhà duy trì đã đánh dấu `swagger-cli` là không còn được dùng nữa. README nói rõ ràng điều này, trích dẫn gánh nặng bảo trì của một lượng lớn người dùng với ít người đóng góp. Nó vẫn hoạt động, và nhiều pipeline vẫn chạy nó ngày nay, nhưng các dự án mới được hướng đến Redocly CLI như là công cụ kế nhiệm được duy trì tích cực. Chúng tôi sẽ đề cập đến quá trình chuyển đổi đó trong phần riêng dưới đây, để bạn có thể quyết định một cách sáng suốt.
Xác thực một thông số kỹ thuật với swagger-cli
Lệnh chính là `validate`. Trỏ nó đến tệp thông số kỹ thuật của bạn:
swagger-cli validate openapi.yaml
Nếu tài liệu hợp lệ, bạn sẽ nhận được một xác nhận một dòng và mã thoát `0`. Nếu có gì đó không ổn, bạn sẽ nhận được một lỗi mô tả vấn đề và mã thoát khác 0, đây chính xác là điều bạn muốn trong một pipeline. `validate` chạy hai kiểm tra ngầm, và bạn có thể tắt một trong hai:
swagger-cli validate --no-schema openapi.yaml
swagger-cli validate --no-spec openapi.yaml
`--no-schema` bỏ qua việc xác thực đối với OpenAPI JSON Schema, kiểm tra cấu trúc xác nhận tài liệu của bạn có hình dạng đúng. `--no-spec` bỏ qua việc xác thực đối với các quy tắc thông số kỹ thuật, kiểm tra ngữ nghĩa phát hiện những thứ như ID hoạt động trùng lặp hoặc một `$ref` không trỏ đến đâu. Hầu hết thời gian bạn muốn cả hai đều bật, đây là mặc định. Các cờ này tồn tại cho những trường hợp hiếm hoi mà một lớp đang báo hiệu một điều gì đó mà bạn có lý do cố ý để cho phép. Những gì `validate` phát hiện tốt: YAML bị lỗi định dạng, thiếu các trường bắt buộc, con trỏ `$ref` bị hỏng, và các lỗi cấu trúc khiến một thông số kỹ thuật không thể phân tích được. Những gì nó không làm là thực thi phong cách của nhóm bạn. Nó sẽ vui vẻ thông qua một thông số kỹ thuật không có mô tả, đặt tên không nhất quán, và không có ví dụ, bởi vì không có điều nào trong số đó vi phạm các quy tắc OpenAPI. Đối với loại kiểm tra có ý kiến như vậy, bạn cần một linter, đó là phần tiếp theo. Nếu việc xác thực là tất cả những gì bạn cần, hướng dẫn chi tiết hơn về [cách xác thực thông số kỹ thuật OpenAPI](https://apidog.com/vi/blog/validate-openapi-specs) so sánh một số công cụ và các trường hợp đặc biệt đáng biết.
Gom các thông số kỹ thuật đa tệp
Các thông số kỹ thuật thực tế hiếm khi nằm trong một tệp duy nhất. Bạn chia các schema thành một thư mục `components/`, tham chiếu chúng bằng `$ref`, và giữ cho tệp gốc dễ đọc. Đó là một quy tắc tốt, nhưng nhiều công cụ hạ nguồn muốn một tài liệu tự chứa duy nhất. Lệnh `bundle` sẽ làm phẳng cây thư mục:
swagger-cli bundle openapi.yaml -o dist/openapi.bundled.yaml -t yaml
Các cờ đáng biết: * `-o, --outfile` ghi kết quả vào một tệp thay vì in ra stdout. * `-t, --type` đặt định dạng đầu ra. Mặc định là `json`, vì vậy hãy truyền `t yaml` nếu bạn muốn đầu ra YAML. * `r, --dereference` nội tuyến hoàn toàn mọi `$ref` thay vì chỉ thu thập các tệp bên ngoài vào một tài liệu. Điều này tạo ra một tệp lớn hơn không còn tham chiếu nào, điều mà một số người tiêu dùng yêu cầu. * `f, --format` kiểm soát thụt lề, mặc định là 2 dấu cách. * `w, --wrap` đặt độ dài dòng để ngắt các chuỗi YAML dài. Sự khác biệt giữa plain bundle và `--dereference` là quan trọng. Một plain bundle giữ các con trỏ `$ref` nội bộ nhưng kéo tất cả các tệp riêng biệt vào một, do đó tài liệu có tính di động. `--dereference` giải quyết mọi tham chiếu thành các đối tượng nội tuyến, điều này làm tăng kích thước tệp nhưng đảm bảo không có người tiêu dùng nào phải giải quyết con trỏ. Sử dụng plain bundle để phân phối và dạng dereferenced chỉ khi một công cụ cụ thể yêu cầu. Một mô hình phổ biến là xác thực và bundle trong một bước như một phần của quá trình build:
swagger-cli validate openapi.yaml && swagger-cli bundle openapi.yaml -o dist/openapi.json
Dấu `&&` có nghĩa là bundle chỉ chạy nếu xác thực thành công, vì vậy một thông số kỹ thuật bị lỗi sẽ không bao giờ tạo ra một artifact build.
Kết nối swagger-cli vào CI
Xác thực có giá trị nhất khi nó chạy trên mỗi thay đổi, không phải khi ai đó nhớ. Hãy đưa nó vào pipeline của bạn như một cổng nhanh chóng. Dưới đây là một bước GitHub Actions làm lỗi bản dựng trên một thông số kỹ thuật không hợp lệ:
name: Validate OpenAPI spec
on:
pull_request:
paths:
- 'openapi.yaml'
- 'components/**'
jobs:
validate-spec:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Validate spec
run: npx @apidevtools/swagger-cli validate openapi.yaml
Bởi vì `swagger-cli validate` thoát với mã khác không khi có thông số kỹ thuật không hợp lệ, bước này sẽ chuyển sang màu đỏ và pull request sẽ hiển thị kiểm tra thất bại. Không cần cấu hình bổ sung. Bộ lọc `paths` giữ cho công việc không chạy khi thông số kỹ thuật không thay đổi, giúp tiết kiệm thời gian CI của bạn. Đây là cổng chất lượng rẻ nhất bạn có thể thêm vào một kho lưu trữ API. Nó chỉ tốn vài giây và ngăn chặn toàn bộ loại lỗi “tài liệu đã nói dối” đến với bất kỳ ai ở hạ nguồn.
Khi bạn cần linting, không chỉ xác thực
Xác thực trả lời một câu hỏi: đây có phải là một tài liệu OpenAPI hợp lệ không? Linting trả lời một câu hỏi khó hơn: đây có phải là một tài liệu OpenAPI tốt theo tiêu chuẩn của nhóm chúng ta không? Hai điều đó không giống nhau, và `swagger-cli` chỉ làm điều đầu tiên. Giả sử hướng dẫn phong cách của bạn yêu cầu mỗi hoạt động phải có `summary`, mỗi thuộc tính phải có `description`, và mỗi đường dẫn phải sử dụng kebab-case. Một thông số kỹ thuật có thể vi phạm cả ba điều đó mà vẫn vượt qua `swagger-cli validate`, bởi vì không có quy tắc nào trong số đó là một phần của thông số kỹ thuật OpenAPI. Một linter cho phép bạn mã hóa và thực thi chúng. Đây là lý do chính khiến các nhóm chuyển sang Redocly CLI, công cụ kế nhiệm được duy trì mà bản thân `swagger-cli` cũng chỉ ra. Nó bao gồm các chức năng xác thực và gom gói tương tự, sau đó thêm một công cụ linting thực sự.
Chuyển sang Redocly CLI
Việc di chuyển khá đơn giản vì tên lệnh tương tự nhau. Cài đặt công cụ kế nhiệm:
npm install -g @redocly/cli
Lệnh tương đương với validate là `lint`. Để khớp chặt chẽ với hành vi cũ, hãy mở rộng bộ quy tắc tối thiểu:
redocly lint --extends=minimal openapi.yaml
Chạy nó với bộ quy tắc mặc định thay vào đó và nó sẽ thực thi một bộ quy tắc được khuyến nghị mạnh mẽ hơn, đây là nơi giá trị linting xuất hiện. Bạn cấu hình các quy tắc trong tệp `redocly.yaml`, đặt mỗi quy tắc thành `error` hoặc `warn`, và thậm chí viết các plugin tùy chỉnh cho các kiểm tra đặc thù của tổ chức. Gom gói ánh xạ gần như một đối một:
redocly bundle openapi.yaml -o dist/openapi.yaml
Tên cờ thay đổi một chút. `-o/--outfile` của `swagger-cli` trở thành `--output`, `-t/--type` trở thành `--ext`, và `-r/--dereference` trở thành `-d/--dereferenced`. Nếu các script cũ của bạn sử dụng các cờ ngắn, một thao tác tìm kiếm và thay thế nhanh chóng sẽ giúp bạn thực hiện. Để so sánh rộng hơn về các công cụ kiểm tra thông số kỹ thuật, bài viết [các công cụ xác thực OpenAPI tốt nhất](https://apidog.com/vi/blog/best-openapi-validator-tools) đặt Redocly bên cạnh các lựa chọn thay thế. Tóm lại: nếu bạn đang bắt đầu mới, hãy sử dụng Redocly CLI. Nếu bạn có một bước `swagger-cli` hiện có đang hoạt động, không cần phải thay đổi gấp, nhưng con đường phía trước đã rõ ràng và việc đổi tên là một thao tác cơ học.
Một nửa những gì công cụ thông số kỹ thuật không thể bao phủ
Đây là giới hạn của mọi công cụ mà chúng ta đã thảo luận cho đến nay. `swagger-cli validate` xác nhận thông số kỹ thuật của bạn được định dạng tốt. `redocly lint` xác nhận nó tuân theo phong cách của bạn. Cả hai đều không gửi một yêu cầu nào đến API đang chạy của bạn. Một thông số kỹ thuật có thể hoàn hảo trên giấy trong khi việc triển khai trả về mã 500, bỏ qua một trường mà nó đã hứa, hoặc hoàn toàn bỏ qua một tham số truy vấn. Để thu hẹp khoảng cách đó, cần phải kiểm thử chức năng: gửi một yêu cầu thực tế đến một điểm cuối thực tế, sau đó xác nhận mã trạng thái, nội dung phản hồi và các giá trị bên trong nó. Đó là một loại công cụ khác, và đó là nơi [Apidog](https://apidog.com) phù hợp với quy trình làm việc. Apidog là một nền tảng API tất cả trong một. Bạn nhập thông số kỹ thuật OpenAPI của mình, và từ định nghĩa đó, bạn nhận được tài liệu tương tác, một máy chủ giả lập, và các kịch bản kiểm thử mà bạn có thể nối chuỗi với các xác nhận, tất cả mà không cần rời khỏi không gian làm việc. Việc nhập trực tiếp; hướng dẫn về [nhập Swagger hoặc OpenAPI và tạo các yêu cầu có thể chạy được](https://apidog.com/vi/blog/swagger-openapi-requests) sẽ hướng dẫn bạn qua đó, và bạn có thể [tạo các bộ sưu tập kiểm thử đầy đủ trực tiếp từ thông số kỹ thuật](https://apidog.com/vi/blog/api-test-collections-generation-openapi-specs) thay vì tự xây dựng chúng. Phần quan trọng đối với terminal là trình chạy dòng lệnh, được phát hành dưới dạng gói npm `apidog-cli`. Bạn cài đặt nó và chạy một kịch bản đã lưu mà không cần giao diện người dùng:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Cờ `-t` là ID kịch bản kiểm thử, `-e` là ID môi trường, và `-r` chọn các định dạng báo cáo như `cli`, `html`, `json`, hoặc `junit`. Giống như `swagger-cli`, nó thoát với mã trạng thái sạch, vì vậy một xác nhận thất bại sẽ làm cho pipeline chuyển sang màu đỏ. Không giống như `swagger-cli`, những gì nó kiểm tra là hành vi trực tiếp của API của bạn, không chỉ là hình dạng của tệp mô tả nó. Để tham khảo đầy đủ các cờ và ví dụ CI, hãy xem [hướng dẫn đầy đủ về Apidog CLI](https://apidog.com/vi/blog/apidog-cli-complete-guide), hoặc chạy `apidog run --help` để xem các tùy chọn hiện tại. Nếu bạn muốn thiết lập kịch bản đầu tiên đó, hãy [tải xuống Apidog](https://apidog.com/download), nhập thông số kỹ thuật của bạn, và lệnh chạy có thể được sao chép từ tab CI/CD của kịch bản.
Một quy trình làm việc terminal hoàn chỉnh
Kết hợp hai phần lại với nhau và bạn sẽ có một pipeline kiểm tra hợp đồng và việc triển khai theo trình tự:
# 1. Thông số kỹ thuật có được định dạng tốt và đúng kiểu không?
redocly lint --extends=minimal openapi.yaml
# 2. Tạo một tài liệu phân phối duy nhất.
redocly bundle openapi.yaml -o dist/openapi.yaml
# 3. API đang chạy có thực sự khớp với hợp đồng không?
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit
Bước một sẽ thất bại nhanh chóng nếu thông số kỹ thuật bị lỗi định dạng hoặc không đúng kiểu. Bước hai tạo ra artifact mà tài liệu và trình tạo SDK của bạn sử dụng. Bước ba gửi lưu lượng truy cập thực và xác nhận các phản hồi, vì vậy một bản dựng xanh có nghĩa là cả hợp đồng và mã đằng sau nó đều hợp lệ. Mỗi bước thoát với mã khác không khi thất bại, vì vậy toàn bộ chuỗi là một cổng duy nhất mà bạn có thể đưa vào bất kỳ trình chạy CI nào có Node. Nếu việc kiểm thử của bạn hiện nay dựa vào một công cụ tuân thủ thông số kỹ thuật đã không còn được phát triển, bài viết về [xác thực API so với thông số kỹ thuật mà không cần Dredd](https://apidog.com/vi/blog/dredd-alternative-api-testing) sẽ đề cập đến ý tưởng hợp đồng-vs-triển khai tương tự từ một góc độ khác.
Lưu ý về swagger-codegen
Những người tìm kiếm “swagger cli” đôi khi thực sự muốn `swagger-codegen`, đây là một công cụ khác với công việc khác. Nó đọc một thông số kỹ thuật OpenAPI và tạo ra các SDK client, server stubs, và tài liệu trong hàng chục ngôn ngữ. Nó thực sự hữu ích để khởi động một client đã được gõ từ một thông số kỹ thuật đã xuất bản, và công bằng mà nói, nó là lựa chọn tạo mã có khả năng nhất trong họ Swagger. Nó không xác thực, lint, hoặc kiểm thử theo nghĩa bài viết này đề cập. Việc tạo mã giả định rằng bạn đã có một thông số kỹ thuật hợp lệ; nếu đầu vào bị lỗi, đầu ra cũng sẽ bị lỗi theo cách tương ứng. Vì vậy, ngay cả trong quy trình làm việc tạo mã, bạn vẫn muốn có một bước xác thực hoặc linting trước đó. Các công cụ này bổ sung cho nhau chứ không thay thế lẫn nhau.