Một tệp Swagger bị hỏng hiếm khi tự thông báo. YAML vẫn phân tích cú pháp tốt. Trang tài liệu vẫn hiển thị. Sau đó, một nhà phát triển frontend tạo ra một client từ spec của bạn, quá trình build thất bại do thiếu trường required, và bạn phát hiện ra mô tả API "đã hoàn thành" của mình có một lỗi chính tả trong một $ref từ ba commit trước. Spec đã sai suốt thời gian đó. Không có gì cho bạn biết cho đến khi nó tốn của ai đó cả một buổi chiều.
Đó là công việc mà một trình xác thực Swagger thực hiện: nó đọc tệp OpenAPI hoặc Swagger của bạn và cho bạn biết, trước khi bất kỳ ai sử dụng nó, liệu tài liệu đó có thực sự hợp lệ hay không. Không phải "trông có đúng không," mà là "có tuân thủ Đặc tả OpenAPI không, có giải quyết mọi tham chiếu không và có mô tả một schema mà một công cụ có thể tin cậy không." Một trình xác thực biến các lỗi cấu trúc âm thầm thành các lỗi lớn, có số dòng mà bạn sửa trong vài giây thay vì phải gỡ lỗi hàng giờ sau đó.
Trình xác thực Swagger thực sự kiểm tra những gì
Trước hết, về tên gọi. "Swagger" và "OpenAPI" mô tả cùng một thứ ở các thời điểm khác nhau trong lịch sử. Định dạng này được gọi là Swagger cho đến phiên bản 2.0, sau đó được tặng cho Sáng kiến OpenAPI và đổi tên; các phiên bản 3.0, 3.1 và 3.2 đều là OpenAPI. Mọi người vẫn nói "swagger validator" theo thói quen, và hầu hết các công cụ đều chấp nhận cả Swagger 2.0 và OpenAPI 3.x. Nếu lịch sử phiên bản không rõ ràng, sự phân tích về Swagger so với OpenAPI sẽ làm sáng tỏ điều đó. Để biết sự khác biệt giữa các phiên bản gần đây, hãy xem những gì đã thay đổi trong OpenAPI 3.2 so với 3.1 so với 3.0.
Một trình xác thực thực sự làm ba công việc, theo thứ tự:
- Phân tích cú pháp. Tệp có hợp lệ là YAML hay JSON không? Một tab lạc, một khóa trùng lặp, một dấu ngoặc chưa đóng, tài liệu sẽ không bao giờ tải. Đây là lỗi dễ bắt nhất và đáng xấu hổ nhất khi phát hành.
- Xác thực cấu trúc. Tài liệu có tuân thủ schema OpenAPI không? Mọi thao tác đều cần một đối tượng
responses. Mọi tham số đều cần một giá trịin. Một$refphải trỏ đến một thứ tồn tại. Đây là nơi hầu hết các lỗi thực sự ẩn náu. - Giải quyết tham chiếu. Các tài liệu OpenAPI chứa đầy các con trỏ
$refđể ghép nối các schema có thể tái sử dụng. Trình xác thực sẽ theo dõi từng con trỏ và thất bại nếu một mục tiêu bị thiếu, vòng lặp theo cách mà spec cấm, hoặc trỏ đến sai tệp.
Vượt qua cả ba và bạn có một tài liệu mà bất kỳ công cụ tương thích nào, trình tạo mã, máy chủ giả lập, trình hiển thị tài liệu, đều có thể đọc mà không bị lỗi. Thất bại ở bất kỳ khâu nào và lỗi sẽ xuất hiện ở một nơi nào đó kém thuận tiện hơn terminal của bạn.
Những lỗi mà nó bắt được và gây rắc rối sau này
Việc xác thực có vẻ trừu tượng cho đến khi bạn thấy những gì có thể bỏ sót nếu không có nó. Đây là những lỗi spec trông vô hại trong trình chỉnh sửa và biến thành các sự cố thực sự sau này.
Con trỏ $ref bị hỏng. Bạn đổi tên một schema từ User thành UserProfile nhưng bỏ sót một tham chiếu sâu trong phần thân phản hồi. YAML vẫn phân tích cú pháp. Tài liệu vẫn hiển thị phần còn lại của trang. Trình tạo mã gặp con trỏ lơ lửng và tạo ra một client với một kiểu dữ liệu bị thiếu, hoặc chỉ đơn giản là bị crash. Một trình xác thực sẽ báo lỗi $ref bị hỏng ngay khi bạn lưu.
Mâu thuẫn giữa schema và ví dụ. Schema của bạn nói age là một số nguyên; ví dụ của bạn hiển thị "age": "thirty". Swagger UI vui vẻ hiển thị cả hai. Một máy chủ giả lập được xây dựng từ spec sau đó trả về một chuỗi trong khi người dùng mong đợi một số, và một bài kiểm tra hợp đồng ở ba nhóm khác nhau chuyển sang màu đỏ vì những lý do không ai có thể truy nguyên từ tệp của bạn.
Thiếu các phần bắt buộc. Một thao tác không có responses. 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 parameters. Một requestBody không có content. Mỗi trường hợp này về mặt kỹ thuật là một tài liệu bị định dạng sai, và mỗi trường hợp tạo ra một triệu chứng khác nhau tùy thuộc vào công cụ nào đọc spec trước tiên.
Lệch kiểu và định dạng. format: date-time trên một trường mà backend của bạn trả về dưới dạng dấu thời gian Unix. type: string trên một thứ thực sự là một mảng. Những trường hợp này vượt qua xác thực cấu trúc nhưng phá vỡ hợp đồng giữa spec và API đang chạy, đây là một vấn đề riêng biệt mà chúng ta sẽ đề cập sau.
Mô hình này nhất quán: một lỗi spec không thể nhìn thấy tại thời điểm bạn tạo ra nó và tốn kém tại thời điểm người khác sử dụng nó. Xác thực đưa chi phí trở lại nơi nó rẻ.
Cách xác thực tệp Swagger thủ công
Bạn không cần một nền tảng để bắt đầu. Có ba cách nhanh chóng để xác thực một spec ngay hôm nay.
Swagger Editor. Dán YAML của bạn vào Swagger Editor và nó sẽ xác thực khi bạn gõ, gạch chân các lỗi kèm theo số dòng ở lề phải. Đây là cách nhanh nhất để kiểm tra nhanh một tệp duy nhất và nó miễn phí. Hạn chế là nó chỉ là một hộp văn bản duy nhất: nó xác thực tài liệu nhưng không làm gì về việc API thực của bạn có còn khớp với nó hay không, và bạn đang tự viết YAML mà không có trình tạo schema trực quan. Đối với việc học định dạng thì không sao. Đối với một spec mà một nhóm phụ thuộc vào, nó chỉ là một tab trong một quy trình làm việc cần nhiều tab.
Một linter như Spectral. Spectral của Stoplight là một công cụ CLI mã nguồn mở vượt ra ngoài việc xác thực thô đến các quy tắc kiểu. Nó kiểm tra tính hợp lệ về cấu trúc và cho phép bạn thực thi một bộ quy tắc: mọi thao tác đều cần mô tả, mọi thuộc tính schema đều cần một kiểu, cách đặt tên tuân theo quy ước của bạn. Spectral thực sự là công cụ tốt nhất trong phân khúc để quản lý kiểu spec trên nhiều tệp, và nếu thiết kế API nhất quán là mối quan tâm của bạn, nó đáng để áp dụng. Bạn chạy nó như sau:
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Đánh đổi ở đây là phạm vi. Spectral xác thực và lint tài liệu. Nó không phải là một trình chạy yêu cầu; nó sẽ không cho bạn biết liệu API mà spec mô tả có thực sự hoạt động theo cách spec tuyên bố hay không. Đó là một lớp khác, và đó là lớp nơi hầu hết các bất ngờ trong môi trường production xuất hiện.
Một điểm cuối xác thực trực tuyến. Dự án Swagger xuất bản một dịch vụ xác thực trả về một huy hiệu pass hoặc fail cho một URL spec được lưu trữ. Nó tiện lợi cho một huy hiệu trong README, nhưng ít hữu ích hơn cho một vòng lặp sửa lỗi tương tác. Để tìm hiểu sâu hơn về các tùy chọn độc lập, chúng tôi có tổng hợp các công cụ xác thực OpenAPI tốt nhất và hướng dẫn chi tiết về cách xác thực các spec OpenAPI.
Cả ba đều xác thực tài liệu. Không có công cụ nào trong số đó thu hẹp khoảng cách giữa một spec hợp lệ và một API chính xác. Khoảng cách đó là nơi phần tiếp theo sẽ đề cập.
Vị trí của Apidog: xác thực spec, sau đó chứng minh API khớp với nó
Apidog là một nền tảng API tất cả trong một: bạn thiết kế schema, gỡ lỗi yêu cầu, xây dựng các kịch bản kiểm thử tự động, giả lập các điểm cuối và xuất bản tài liệu trong một không gian làm việc duy nhất. Xác thực spec không phải là một công cụ riêng biệt mà bạn gắn vào; nó là một thuộc tính của việc làm việc trong nền tảng.
Khi bạn nhập một tệp Swagger hoặc OpenAPI, hoặc thiết kế một tệp trong trình chỉnh sửa trực quan, Apidog sẽ phân tích cú pháp và xác thực nó ngay từ đầu. Một tài liệu bị định dạng sai, một $ref bị hỏng, một tham số không có kiểu, tất cả những điều này sẽ xuất hiện ngay khi bạn làm việc, chứ không phải sau khi đi qua ba công cụ khác. Bởi vì trình chỉnh sửa là trực quan, toàn bộ loại lỗi YAML viết tay sẽ không bao giờ xảy ra: bạn không thể quên giá trị in trên một tham số khi trường đó là một menu thả xuống bắt buộc. Spec hợp lệ ngay từ khi xây dựng.
Điều đó giải quyết vấn đề tài liệu. Vấn đề khó hơn là sự trôi lệch, sự không đồng nhất chậm chạp giữa một spec nói một đằng và một API làm một nẻo. Một trình xác thực độc lập không thể bắt được điều này, vì tệp vẫn hợp lệ; chính dịch vụ đang chạy mới là sai. Đây là chế độ lỗi đằng sau rất nhiều tài liệu Swagger và bộ sưu tập Postman bị lệch.
Apidog giải quyết vấn đề này bằng cách biến spec thành nguồn đáng tin cậy cho việc kiểm thử. Bạn tạo các kịch bản kiểm thử trực tiếp từ spec OpenAPI của mình, sau đó khẳng định rằng các phản hồi thực tế khớp với schema bạn đã khai báo. Khi spec nói age là một số nguyên và API trả về một chuỗi, bài kiểm thử sẽ thất bại, và nó thất bại so với spec, chứ không phải so với một bản sao được duy trì thủ công. Câu hỏi về trình xác thực trở thành một câu hỏi liên tục: không phải "tệp này có hợp lệ khi tôi lưu nó không" mà là "API trực tiếp có còn đúng với hợp đồng của nó ngay bây giờ không." Nếu bạn muốn biết cơ chế khẳng định, Các khẳng định API: hướng dẫn thực hành bao gồm việc xác thực hình dạng, trạng thái và các trường phản hồi.
Đối với các nhóm muốn việc xác thực được thực thi tự động thay vì phải ghi nhớ, Apidog cũng bao gồm việc giữ cho các API tuân thủ các tiêu chuẩn OpenAPI như một phần của vòng lặp thiết kế.
Chạy xác thực dựa trên spec trong CI với Apidog CLI
Một trình xác thực chỉ chạy khi ai đó mở trình chỉnh sửa là một trình xác thực cuối cùng sẽ bị bỏ qua. Giải pháp là đưa việc xác thực vào pipeline, nơi nó chạy trên mỗi lần push mà không có sự can thiệp của con người. Đó là mục đích của trình chạy dòng lệnh Apidog.
CLI là một gói npm có tên apidog-cli. Nó chạy các kịch bản kiểm thử bạn đã xây dựng trong Apidog, không cần giao diện người dùng, từ bất kỳ môi trường nào có Node.js. Cài đặt nó bằng một lệnh:
npm install -g apidog-cli
Sau đó, chạy một kịch bản đã lưu, cùng kịch bản khẳng định phản hồi trực tiếp của bạn khớp với spec, đối với một môi trường:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Một vài lưu ý về chức năng của các cờ đó. -t là ID kịch bản kiểm thử. -e là ID môi trường, để bạn có thể chỉ định cùng một kiểm tra cho môi trường staging trong một pull request và cho môi trường production sau khi triển khai. -r chọn định dạng báo cáo: cli cho đầu ra log build dễ đọc, và bạn có thể thêm html, json, hoặc junit để cấp dữ liệu cho bảng điều khiển CI. --access-token thuộc về một secret CI, không bao giờ nằm trong mã. Bạn tạo cả token và lệnh có sẵn từ tab CI/CD của kịch bản bên trong Apidog. Để biết toàn bộ các cờ, hãy chạy apidog run --help hoặc đọc hướng dẫn đầy đủ về Apidog CLI.
Chi tiết khiến đây trở thành một cổng bảo vệ thực sự: CLI thoát với mã trạng thái khác 0 khi một khẳng định thất bại. Các hệ thống CI đọc mã thoát đó. Một kiểm tra schema thất bại sẽ khiến bước đó thất bại, điều này làm thất bại toàn bộ công việc, và chặn việc hợp nhất. Vì vậy, ngay khi API của bạn không còn khớp với hợp đồng OpenAPI của nó, quá trình build sẽ chuyển sang màu đỏ, trước khi thay đổi được triển khai, chứ không phải sau khi một người dùng gửi ticket. Đó là sự khác biệt giữa việc xác thực một tệp một lần và xác thực hợp đồng trên mỗi commit. Hành vi mã thoát tương tự là lý do tại sao trình chạy có thể tích hợp vào bất kỳ nền tảng CI nào, giống như chạy các bộ sưu tập Postman trong CI mà không cần Newman.
Tải xuống Apidog nếu bạn muốn xác thực spec và kiểm thử hợp đồng tại cùng một nơi mà nhóm của bạn đã thiết kế API.
Quy trình xác thực thực tế
Tổng hợp các phần lại, đây là một chuỗi các bước giúp bắt lỗi spec ở mọi giai đoạn thay vì chỉ ở giai đoạn cuối:
- Thiết kế hoặc nhập trong một trình chỉnh sửa có khả năng xác thực. Cho dù bạn nhập một tệp Swagger hiện có hay xây dựng nó trong trình thiết kế trực quan của Apidog, tài liệu sẽ được phân tích cú pháp và xác thực cấu trúc ngay từ đầu. Các tham chiếu bị hỏng và các kiểu bị thiếu sẽ xuất hiện ngay lập tức.
- Lint để kiểm tra kiểu nếu bạn có một bộ quy tắc. Nếu tổ chức của bạn thực thi các quy tắc đặt tên và mô tả, hãy chạy Spectral như một kiểm tra nhanh trước khi commit. Tính hợp lệ và phong cách nội bộ là những mối quan tâm khác nhau; hãy bao quát cả hai.
- Tạo kiểm thử từ spec. Biến tài liệu OpenAPI thành các kịch bản kiểm thử để các khẳng định của bạn được gắn với cùng một định nghĩa mà bạn phát hành, chứ không phải một bản sao riêng biệt bị lệch.
- Kiểm soát mọi lần push bằng CLI. Kết nối
apidog runvào pipeline của bạn để sự không khớp giữa spec và thực tế tự động làm thất bại quá trình build. - Coi spec là nguồn đáng tin cậy. Khi thiết kế thay đổi, các kiểm thử sẽ trỏ đến cùng một tệp, vì vậy không có gì phải đồng bộ hóa thủ công.
Các bước 1 và 2 xác thực tài liệu. Các bước 3 đến 5 xác thực hợp đồng. Bạn cần cả hai, và nơi rẻ nhất để thực hiện tất cả chúng là một không gian làm việc duy nhất thay vì bốn tab trình duyệt.
Phiên bản ngắn gọn
Một trình xác thực Swagger bắt các lỗi cấu trúc, tham chiếu bị hỏng, kiểu bị thiếu, YAML bị định dạng sai, những lỗi này không thể nhìn thấy khi bạn viết chúng và tốn kém khi người khác đọc chúng. Xác thực tài liệu là mức sàn, không phải mức trần. Các lỗi thực sự đến môi trường production là những lỗi mà một spec hợp lệ lặng lẽ ngừng khớp với một API đang thay đổi, và không có trình xác thực cấp độ tệp nào có thể nhìn thấy những lỗi đó.
Giải pháp là xác thực ở hai lớp và đặt cả hai ở một nơi: xác thực tài liệu khi bạn thiết kế, sau đó xác thực hợp đồng trên mỗi lần push bằng cách khẳng định các phản hồi thực tế so với spec. Apidog thực hiện lớp đầu tiên thông qua quá trình xây dựng và lớp thứ hai thông qua các kịch bản mà trình chạy apidog-cli kiểm soát trong CI. Spec vẫn là nguồn đáng tin cậy, quá trình build sẽ chuyển sang màu đỏ ngay khi thực tế lệch khỏi nó, và một tệp Swagger bị hỏng sẽ không còn là thứ bạn phát hiện ra quá muộn vào một buổi chiều.