Một đặc tả OpenAPI là một hợp đồng. Các trình tạo mã đọc nó, tài liệu được xây dựng từ nó, các máy chủ giả lập (mock server) chạy trên nó và các SDK máy khách (client SDK) được tạo ra từ nó. Khi đặc tả bị sai, mỗi một thành phần phụ thuộc đó đều thừa hưởng lỗi. Một trình xác thực (validator) sẽ phát hiện ra vấn đề trong tệp đặc tả, trước khi nó lan rộng.
Bài tổng hợp này bao gồm các công cụ xác thực OpenAPI đáng sử dụng, mỗi công cụ giỏi về mặt nào và cách chúng phù hợp với một quy trình làm việc thực tế. Một số kiểm tra cú pháp thô. Những công cụ khác thực thi các quy tắc về phong cách và thiết kế. Thiết lập tốt nhất thường kết hợp cả hai, và hướng dẫn này giải thích cách để kết hợp chúng.
Tại sao việc xác thực đặc tả lại quan trọng
Có hai vấn đề riêng biệt mà một trình xác thực giải quyết, và việc gộp chung chúng lại sẽ gây ra sự nhầm lẫn.
Đầu tiên là tính chính xác. Liệu tệp có phải là OpenAPI hợp lệ hay không? Một khối YAML bị thụt lề sai, một $ref không trỏ đến đâu, một phản hồi thiếu description bắt buộc, một lược đồ (schema) có lỗi chính tả trong tên kiểu. Đây là những lỗi khách quan. Tệp hoặc là phân tích được theo lược đồ OpenAPI hoặc là không. Một trình xác thực tính chính xác sẽ cho bạn câu trả lời có hoặc không.
Thứ hai là chất lượng. Đặc tả hợp lệ, nhưng nó có tốt không? Mọi thao tác (operation) nên có một bản tóm tắt. Tên đường dẫn (path name) nên nhất quán. Mọi phản hồi lỗi nên được ghi lại. Bảo mật nên được khai báo. Không điều nào trong số này được yêu cầu bởi lược đồ OpenAPI, nhưng việc bỏ qua chúng sẽ tạo ra một đặc tả hợp lệ về mặt kỹ thuật nhưng lại khó sử dụng. Một công cụ kiểm tra cú pháp (linter) sẽ thực thi các quy tắc thiết kế này. Việc phát hiện sớm cả hai loại vấn đề sẽ rẻ hơn nhiều so với việc phát hiện chúng sau khi một SDK đã được phát hành, đây cũng là logic đằng sau kiểm thử hợp đồng API một cách rộng rãi hơn.
Các công cụ xác thực đáng biết
Swagger Editor
Swagger Editor là trình soạn thảo dựa trên trình duyệt chính thức của dự án OpenAPI. Bạn dán hoặc viết đặc tả của mình ở bên trái và xem các lỗi xác thực cùng bản xem trước đã được render ở bên phải, theo thời gian thực. Đây là cách nhanh nhất để kiểm tra xem một đặc tả có hợp lệ về mặt cú pháp hay không, không cần cài đặt. Nó rất tuyệt vời cho việc chỉnh sửa và kiểm tra nhanh, ít phù hợp hơn cho các lượt chạy tự động trong pipeline. Swagger Editor miễn phí và chạy hoàn toàn trên trình duyệt.
Spectral
Spectral, từ Stoplight, là công cụ kiểm tra cú pháp mà hầu hết các nhóm sử dụng để thực thi chất lượng. Nó đi kèm với các bộ quy tắc cho OpenAPI và AsyncAPI, và giá trị thực sự nằm ở các quy tắc tùy chỉnh. Bạn viết các quy tắc bằng YAML hoặc JavaScript để thực thi các quy ước riêng của mình, chẳng hạn như yêu cầu mọi thao tác phải có mô tả hoặc cấm dấu gạch chéo ở cuối đường dẫn. Nó chạy từ dòng lệnh, điều này khiến nó phù hợp tự nhiên với CI. Dự án Spectral là mã nguồn mở.
openapi-spec-validator
openapi-spec-validator là một công cụ Python chuyên biệt thực hiện tốt một công việc: kiểm tra một đặc tả so với lược đồ OpenAPI chính thức cho các phiên bản 2.0, 3.0 và 3.1. Nó không có ý kiến gì về phong cách. Nó cho bạn biết liệu tệp có đúng cấu trúc hay không. Là một thư viện hoặc một CLI, nó tích hợp gọn gàng vào các bước xây dựng dựa trên Python và các pre-commit hook. Khi bạn muốn một cổng kiểm tra tính chính xác cứng nhắc theo kiểu đạt/trượt, đây là một lựa chọn rõ ràng.
Apidog
Apidog xác thực đặc tả như một phần của quy trình làm việc thiết kế tích hợp. Khi bạn xây dựng hoặc nhập một định nghĩa OpenAPI, nó sẽ báo cáo các vấn đề cấu trúc trong trình soạn thảo. Tính năng đặc biệt hơn của nó là xác thực thời gian chạy: nó kiểm tra các phản hồi API trực tiếp so với lược đồ được khai báo trong đặc tả của bạn, nhờ đó bạn phát hiện được sự sai lệch khi triển khai không còn khớp với hợp đồng. Điều đó thu hẹp khoảng cách giữa một tài liệu hợp lệ và một API chính xác. Tải xuống Apidog để thiết kế và xác thực các đặc tả trong một công cụ duy nhất.
Redocly CLI
Redocly CLI kết hợp kiểm tra cú pháp (linting), xác thực và tạo tài liệu. Nó xác thực theo lược đồ OpenAPI, đi kèm một bộ quy tắc có thể cấu hình và có thể giải quyết các đặc tả đa tệp thành một gói duy nhất. Các nhóm đã render tài liệu bằng Redoc sẽ có được khả năng xác thực trong cùng một bộ công cụ mà không cần thêm một phụ thuộc nào khác.
Vacuum
Vacuum là một công cụ kiểm tra cú pháp OpenAPI nhanh được viết bằng Go. Điểm mạnh của nó là tốc độ trên các đặc tả rất lớn, nơi một số công cụ kiểm tra cú pháp dựa trên JavaScript bị chậm lại. Nó tương thích với các quy tắc kiểu Spectral, vì vậy một nhóm có thể chuyển đổi với ít công sức làm lại. Đối với một monorepo với bề mặt API rộng lớn, sự khác biệt về hiệu suất là đáng kể.
Bảng so sánh
| Công cụ | Loại | Kiểm tra | Chạy trong CI | Tốt nhất cho |
|---|---|---|---|---|
| Swagger Editor | Trình soạn thảo trình duyệt | Cú pháp, lược đồ | Không | Chỉnh sửa trực tiếp và kiểm tra nhanh |
| Spectral | Công cụ kiểm tra cú pháp CLI | Phong cách, quy tắc tùy chỉnh | Có | Thực thi các quy ước thiết kế |
| openapi-spec-validator | CLI / Thư viện Python | Tính chính xác của lược đồ | Có | Cổng đạt/trượt cứng nhắc |
| Apidog | Nền tảng tích hợp | Lược đồ + sai lệch thời gian chạy | Có | Thiết kế cộng với xác thực phản hồi |
| Redocly CLI | CLI | Lược đồ, phong cách, đóng gói | Có | Tài liệu và xác thực cùng nhau |
| Vacuum | Công cụ kiểm tra cú pháp CLI | Phong cách, quy tắc Spectral | Có | Các đặc tả rất lớn, tốc độ |
Cách xây dựng một quy trình xác thực
Bạn không chọn một công cụ. Bạn kết hợp chúng lại.
Bắt đầu từ nơi bạn chỉnh sửa. Khi viết một đặc tả, hãy sử dụng Swagger Editor hoặc một nền tảng tích hợp để các lỗi hiển thị ngay khi bạn nhập. Điều này giúp bắt các lỗi rõ ràng ngay lập tức và rẻ hơn nhiều so với việc phát hiện chúng sau này.
Thêm một cổng kiểm tra tính chính xác vào CI. Chạy openapi-spec-validator hoặc một công cụ CLI tương đương trên mỗi pull request liên quan đến đặc tả. Nếu tệp không xác thực được theo lược đồ OpenAPI, quá trình xây dựng sẽ thất bại. Điều này là không thể thương lượng và mang tính nhị phân.
Thêm một cổng kiểm tra chất lượng bên cạnh. Chạy Spectral, hoặc Vacuum đối với các đặc tả lớn, với một bộ quy tắc mà nhóm của bạn đã thống nhất. Bắt đầu với các quy tắc OpenAPI có sẵn, sau đó thêm các quy tắc tùy chỉnh cho các quy ước riêng của bạn. Giữ bộ quy tắc trong kiểm soát phiên bản để nó phát triển cùng với API. Đây là kỷ luật tương tự giúp tự động hóa kiểm thử trong CI/CD trở nên đáng tin cậy: kiểm tra chạy mỗi lần, không phải khi ai đó nhớ ra.
Cuối cùng, xác thực API đang chạy so với đặc tả. Một đặc tả có thể hoàn hảo trong khi quá trình triển khai đã sai lệch so với nó. Xác thực thời gian chạy, dù thông qua Apidog hay các bài kiểm thử hợp đồng trong bộ kiểm thử của bạn, sẽ xác nhận API vẫn khớp với hợp đồng của nó. Về phía kiểm thử, viết các xác nhận API hữu ích bao gồm cách kiểm tra phản hồi so với lược đồ đã được ghi lại.
Một lỗi phổ biến: chỉ xác thực một lần
Nhiều nhóm chỉ xác thực một đặc tả một lần, khi họ viết nó lần đầu, sau đó không bao giờ nữa. Đặc tả dần trở nên lỗi thời từ đó. Một nhà phát triển thêm một điểm cuối trong mã và quên đặc tả. Ai đó điều chỉnh hình dạng phản hồi. Sáu tháng sau, đặc tả mô tả một API không còn tồn tại, và các SDK và tài liệu được tạo ra lặng lẽ sai.
Xác thực phải liên tục. Kết nối nó vào CI để mọi thay đổi đối với đặc tả đều được kiểm tra, và mọi thay đổi đối với API đều được kiểm tra so với đặc tả. Xử lý lỗi đặc tả theo cách tương tự như bạn xử lý một bài kiểm thử đơn vị thất bại: quá trình xây dựng không vượt qua. Nguyên tắc này giống như nguyên tắc đằng sau kiểm thử tự động nói chung, đó là một kiểm tra chỉ có giá trị nếu nó chạy mà không cần ai quyết định chạy nó.
Nó cũng giúp ích khi xác thực với phiên bản OpenAPI chính xác. Phiên bản 3.1 đã điều chỉnh OpenAPI với JSON Schema, điều này đã thay đổi cách một số cấu trúc lược đồ hoạt động. Nếu công cụ của bạn giả định 3.0 nhưng đặc tả của bạn khai báo 3.1, bạn có thể nhận được kết quả sai lệch. Đặc tả OpenAPI chính thức ghi lại sự khác biệt giữa các phiên bản, và hầu hết các trình xác thực đều cho phép bạn ghim phiên bản một cách rõ ràng.
Những gì trình xác thực phát hiện mà bạn sẽ bỏ lỡ
Điều đáng nói cụ thể về các loại vấn đề mà xác thực đưa ra, bởi vì "đặc tả bị sai" quá mơ hồ để hành động.
Các lỗi cấu trúc là dễ hình dung nhất. Một $ref trỏ đến một lược đồ không tồn tại. Một đối tượng phản hồi không có description, điều mà OpenAPI yêu cầu. Một tham số đường dẫn được khai báo trong mẫu URL nhưng không bao giờ được định nghĩa trong danh sách parameters. Một lược đồ nói type: integer trong khi ví dụ hiển thị một chuỗi. Một trình xác thực tính chính xác sẽ gắn cờ từng lỗi này, và nếu không có nó, mỗi lỗi đó sẽ làm hỏng một trình tạo mã hoặc tạo ra một SDK bị lỗi.
Các vấn đề về chất lượng tinh tế hơn và phổ biến hơn. Một thao tác không có operationId, điều này làm cho tên phương thức máy khách được tạo ra trở nên xấu xí hoặc không ổn định. Các trường hợp viết hoa đường dẫn không nhất quán, trong đó một số tuyến đường sử dụng snake_case và những tuyến khác sử dụng camelCase. Các điểm cuối ghi lại phản hồi 200 nhưng không bao giờ có 400 hoặc 401, vì vậy người tiêu dùng không biết lỗi trông như thế nào. Một nội dung yêu cầu được đánh dấu là tùy chọn trong khi API thực sự yêu cầu nó. Không điều nào trong số này làm hỏng trình phân tích cú pháp, nhưng tất cả chúng đều làm cho API khó sử dụng hơn, và một công cụ kiểm tra cú pháp là thứ giữ vững giới hạn này. Mối liên hệ với hành vi thực tế là điều mà kiểm thử hợp đồng API xác minh sau khi bản thân đặc tả đã sạch.
Kết hợp xác thực vào quy trình làm việc thiết kế trước
Nhiều nhóm hiện nay thiết kế API trước khi viết mã, tạo đặc tả OpenAPI trước tiên và tạo các stub máy chủ, giả lập (mock) và tài liệu từ đó. Xác thực thậm chí còn quan trọng hơn trong mô hình đó, bởi vì đặc tả không phải là tài liệu của một API hiện có; nó là nguồn sự thật mà mọi thứ khác được xây dựng từ đó. Một lỗi trong đặc tả sẽ trở thành một lỗi trong máy chủ được tạo ra.
Trong một luồng thiết kế trước, hãy xác thực ngay tại thời điểm thiết kế. Các kiểm tra cấp độ trình soạn thảo sẽ phát hiện lỗi khi đặc tả đang hình thành, trước khi bất kỳ quá trình tạo mã nào chạy. Sau đó, các cổng CI xác nhận không có gì bị thoái lui. Bởi vì đặc tả cũng điều khiển máy chủ giả lập, một đặc tả sạch có nghĩa là máy chủ giả lập hoạt động chính xác, điều này cho phép các nhóm front-end và máy khách xây dựng dựa trên một đối tượng thay thế đáng tin cậy. Nếu bạn muốn xem cách một đặc tả cung cấp cho việc giả lập, hướng dẫn của chúng tôi về giả lập một API để kiểm thử cho thấy mối liên hệ. Kỷ luật này tự nó sẽ có ích: mỗi giờ dành để giữ đặc tả hợp lệ sẽ tiết kiệm vài giờ gỡ lỗi các máy khách không khớp sau này.
Các câu hỏi thường gặp
Sự khác biệt giữa trình xác thực OpenAPI và công cụ kiểm tra cú pháp (linter) là gì?
Trình xác thực kiểm tra xem đặc tả có đúng cấu trúc theo lược đồ OpenAPI hay không, đưa ra câu trả lời đạt hoặc trượt. Công cụ kiểm tra cú pháp kiểm tra chất lượng và phong cách, chẳng hạn như liệu mọi thao tác có mô tả hay không hoặc liệu việc đặt tên đường dẫn có nhất quán hay không. Nhiều công cụ thực hiện cả hai, nhưng chúng trả lời các câu hỏi khác nhau, và một quy trình làm việc mạnh mẽ sử dụng cả hai.
Tôi có thể xác thực một đặc tả OpenAPI miễn phí không?
Có. Swagger Editor, Spectral, openapi-spec-validator, Redocly CLI và Vacuum đều miễn phí và mã nguồn mở. Apidog xác thực đặc tả trên gói miễn phí của nó và bổ sung các kiểm tra thời gian chạy. Không có lý do gì để bỏ qua xác thực vì lý do chi phí.
Tôi có nên xác thực OpenAPI 3.0 và 3.1 khác nhau không?
Bạn xác thực chúng bằng các công cụ tương tự, nhưng hãy ghim phiên bản. OpenAPI 3.1 đã điều chỉnh với JSON Schema và thay đổi một số hành vi của lược đồ, vì vậy một trình xác thực mong đợi 3.0 có thể báo cáo lỗi sai trên một đặc tả 3.1. Hãy đảm bảo công cụ của bạn hỗ trợ phiên bản mà đặc tả của bạn khai báo.
Việc xác thực đặc tả nên chạy ở đâu?
Ở hai nơi. Trực tiếp trong trình soạn thảo của bạn khi viết đặc tả, để lỗi hiển thị ngay lập tức, và trong CI trên mỗi pull request, để không có gì được hợp nhất với một đặc tả bị hỏng hoặc chất lượng thấp. Xác thực chỉ trong trình soạn thảo dễ bị bỏ qua; xác thực CI thì không.
Làm cách nào để tôi kiểm tra xem API của mình có khớp với đặc tả của nó không?
Xác thực đặc tả chỉ xác nhận tài liệu là chính xác, chứ không phải việc triển khai khớp với nó. Để phát hiện sự sai lệch, hãy chạy kiểm thử hợp đồng hoặc xác thực thời gian chạy so sánh các phản hồi API trực tiếp với lược đồ trong đặc tả. Apidog thực hiện điều này trực tiếp, và các framework kiểm thử hợp đồng thực hiện điều đó trong bộ kiểm thử.