Trình Kiểm Tra OpenAPI

Về Trình Kiểm Tra OpenAPI

Hầu hết đội ngũ tạo hoặc viết tay tài liệu OpenAPI rồi không bao giờ chạy qua linter cho đến khi SDK khách hàng vỡ trong production. Công cụ này cho bạn lượt rà soát đầu tiên nhanh chóng, hoàn toàn trong trình duyệt: dán spec OpenAPI 3.0 hoặc 3.1 ở dạng JSON hoặc YAML, nhận kiểm tra hợp lệ về cấu trúc, tóm tắt từng endpoint và danh sách ưu tiên các vấn đề phổ biến — thiếu operationId, tham số đường dẫn không khai báo, thiếu 401/403 trên endpoint đã xác thực, thao tác ghi không có phản hồi 400/422 cho lỗi xác thực, đối tượng phản hồi không có mô tả và request body không có ví dụ.

Ba mức nghiêm ngặt giúp bạn tập trung theo độ trưởng thành API: Cơ bản cho bản phác thảo, Khuyến nghị cho review production và Nghiêm ngặt cho spec sẵn sàng sinh SDK. Không spec nào rời khỏi trình duyệt.

Công cụ có kiểm tra theo toàn bộ JSON Schema OpenAPI 3.1 không?

Không hoàn toàn — chúng tôi triển khai tập hợp con thực dụng, tập trung vào các vấn đề thực sự gây lỗi sinh SDK, docs hỏng và lỗ hổng bảo mật trong production. Chúng tôi kiểm tra các trường gốc bắt buộc (phiên bản openapi, info.title, info.version), khai báo tham số đường dẫn, viết hoa/thường của phương thức HTTP, độ phủ mã phản hồi, cấu trúc request body với thao tác ghi và mối tương quan giữa security/phản hồi. Để kiểm tra schema đầy đủ theo meta-schema chính thức, hãy chạy CI với Spectral, Redocly CLI hoặc vacuum sau lượt rà này — chúng tải JSON Schema và áp dụng hàng nghìn quy tắc. Công cụ trình duyệt là rà soát hằng ngày; CI là cổng kiểm soát.

Tại sao 401 và 403 bị báo thiếu khi endpoint rõ ràng yêu cầu xác thực?

Vì khách hàng, trình sinh SDK và trình khám phá API cần hình dạng phản hồi rõ ràng để xử lý lỗi đúng cách. Khai báo `security: [{bearerAuth: []}]` cho biết cần xác thực, nhưng nếu bạn chỉ tài liệu hoá `200: OK`, SDK sinh ra không có kiểu cho body 401 — vì vậy khi token hết hạn, client ném lỗi parse mờ mịt thay vì AuthError có kiểu. Hãy thêm ít nhất `401: { description: Token không hợp lệ hoặc thiếu }` và lý tưởng là schema với trường `code`, `message`. Với endpoint phân quyền (POST/PUT/DELETE/PATCH), thêm cả 403 Forbidden để SDK phân biệt 'chưa xác thực' với 'sai quyền'. Tắt kiểm tra nếu bạn xử lý lỗi auth đồng nhất ở gateway.

OpenAPI 3.0 và 3.1 khác nhau ra sao và công cụ có hỗ trợ cả hai không?

OpenAPI 3.1 đồng bộ từ vựng với JSON Schema 2020-12: `nullable: true` được thay bằng `type: [string, null]`, `exclusiveMinimum/Maximum` chuyển sang số thay vì boolean, `example` trở thành `examples` (mảng), webhook là công dân hạng nhất và `$ref` có thể đứng cùng các từ khoá khác. Trình kiểm tra phát hiện 3.0.x hoặc 3.1.x qua trường `openapi` và áp dụng cùng kiểm tra cấu trúc (quy tắc lint phần lớn trùng nhau). Nếu trộn quy ước — như `nullable: true` trong spec `openapi: 3.1.0` — đa số công cụ vẫn chịu được nhưng đầu ra SDK có thể bất ngờ. Với repo nhiều phiên bản, hãy chốt một phiên bản chính cho mỗi project.

Tại sao parser YAML lỗi với một số spec nhưng phiên bản JSON lại chạy ổn?

Chúng tôi cố ý dùng parser YAML nhỏ gọn (không có anchor, không có merge key `<<`, không có tag `!!type`, không có stream nhiều tài liệu `---`) để giữ công cụ offline và nhẹ. ~95% spec thực mà chúng tôi thử đều parse ổn, nhưng spec dùng nhiều anchor YAML (thường để dedupe phản hồi chung) sẽ lỗi. Hai cách xử lý: (1) xuất YAML sang JSON bằng `npx js-yaml spec.yaml > spec.json` — mở rộng anchor xảy ra khi chuyển đổi; (2) inline anchor thủ công. Thông báo lỗi sẽ chỉ ra dòng. Nếu cần hỗ trợ YAML đầy đủ, dùng Spectral hoặc Redocly CLI trên desktop với js-yaml đầy đủ.

'Tham số đường dẫn không khai báo' nghĩa là gì và tại sao làm hỏng client?

Khi template URL chứa `{petId}` (hoặc `{name}` bất kỳ), mỗi placeholder phải xuất hiện trong danh sách `parameters` của thao tác với `in: path` và `required: true`. Nếu `{petId}` có trong URL nhưng thiếu trong parameters, các trình sinh như openapi-generator, oapi-codegen, Kiota và openapi-typescript không thể tạo tham số có kiểu — chúng bỏ qua thao tác, sinh method không tham số với chuỗi `{petId}` cứng trong URL, hoặc crash. Trình kiểm tra phát hiện cả hai chiều: tham số trong URL nhưng chưa khai báo và đã khai báo nhưng không có trong path. Sửa bằng cách thêm khai báo thiếu hoặc bỏ phần thừa — URL là nguồn sự thật.

Có phải mỗi operation cần operationId duy nhất và quy ước đặt tên nào tốt nhất?

Có — các trình sinh dùng operationId làm tên method trong SDK. Nếu thiếu, chúng tự đặt từ method + path, cho ra tên xấu xí và không ổn định như `getPetsPetId`. Quy ước: động từ + tài nguyên + bổ ngữ, camelCase: `listPets`, `getPet`, `createPet`, `updatePet`, `deletePet`, `searchPets`, `getPetVaccinations`. Giữ operationId duy nhất toàn cục (vài trình sinh dùng namespace theo tag, nhiều cái không). Với danh sách phân trang, ưu tiên `listPets` hơn `getPets` để chỉ rõ tính nhiều. Với batch dùng `bulkCreatePets`. Trình kiểm tra báo WARN khi thiếu operationId — sửa trước khi client ngoài tiêu thụ spec.

Có dùng được cho spec OpenAPI do AI sinh (LLM tạo định nghĩa API) không?

Đặc biệt phù hợp. Spec OpenAPI do LLM sinh (qua prompt như 'thiết kế API cho X') liên tục mắc cùng những lỗi: thiếu mô tả phản hồi, tham số đường dẫn khai báo nhưng không có trong URL hoặc ngược lại, phương thức viết thường trộn viết hoa, thiếu 401 trên endpoint bảo mật, request body có ví dụ nhưng không schema và quên các phản hồi lỗi. Dán đầu ra LLM vào đây như bước kiểm tra đầu tiên trước khi đưa vào trình sinh code hay tool docs. Sự kết hợp validate cấu trúc + bảng endpoint + cảnh báo lint bắt khoảng 80% ảo giác LLM trong thử nghiệm nội bộ với Claude, GPT-4 và Gemini.

Công cụ có hỗ trợ Swagger 2.0 hay chỉ OpenAPI 3.x?

Spec Swagger 2.0 (`swagger: "2.0"` ở gốc) được nhận diện và đánh dấu khuyến nghị nâng cấp — công cụ không chạy quy tắc lint trên chúng. Swagger 2.0 đã đóng băng tính năng từ 2014 và hệ sinh thái rộng (Spectral, Redocly, Stoplight, Postman, AWS API Gateway, Apigee, Kong) đều ưu ái OpenAPI 3.x. Chuyển đổi bằng `swagger2openapi spec.json` (npm package) tự động xử lý 90%+ di chuyển: kiểu `body` chuyển vào requestBody, definitions chuyển sang components.schemas và `host`/`basePath`/`schemes` gộp vào mảng servers. Sau khi chuyển, dán vào đây để lint kết quả trước khi merge.