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, hoặc tải lên tệp openapi.yaml / openapi.json của bạn, rồi 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 (kể cả tham số dùng chung ở cấp path item), 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ụ.

Công cụ cũng duyệt mọi $ref trong tài liệu và đánh dấu lỗi các tham chiếu cục bộ chưa giải được (một #/components/schemas/Foo treo lơ lửng) cùng các ref bên ngoài/từ xa mà nó không thể tải offline — nguyên nhân lớn nhất khiến trình sinh code crash và thao tác bị bỏ rơi âm thầm. 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.

Làm sao kiểm tra tệp OpenAPI hoặc Swagger online?

Ba bước, tất cả ngay trong trình duyệt. (1) Dán tài liệu OpenAPI 3.0 hoặc 3.1 vào ô dưới dạng JSON hoặc YAML, hoặc tải lên tệp openapi.yaml, openapi.yml hay openapi.json bằng nút tệp phía trên vùng văn bản. (2) Chọn mức nghiêm ngặt — Cơ bản cho bản phác thảo, Khuyến nghị cho review production, Nghiêm ngặt cho spec sẵn sàng sinh SDK — và bật kiểm tra phản hồi auth cùng ví dụ tùy ý. (3) Bấm Kiểm tra spec. Bạn nhận ngay tóm tắt đạt/không đạt, bốn chỉ số (path, thao tác, schema, ref đã giải), bảng endpoint kèm phương thức và cờ auth, và danh sách vấn đề sắp xếp theo mức độ (LỖI / CẢNH BÁO / INFO). Không gì được gửi lên máy chủ — việc phân tích và lint chạy hoàn toàn trên máy bạn, nên an toàn cho API riêng tư và nội bộ.

Công cụ phát hiện tham chiếu $ref hỏng hoặc chưa giải được như thế nào?

Nó duyệt toàn bộ tài liệu đã phân tích, thu thập mọi con trỏ "$ref" và giải từng cái. Con trỏ cục bộ như #/components/schemas/Pet được giải theo quy tắc JSON-pointer (bao gồm bỏ thoát ~1 → / và ~0 → ~); nếu thành phần đích không tồn tại, ref bị đánh dấu LỖI — đây là nguyên nhân số 1 khiến openapi-generator, oapi-codegen, Kiota, openapi-typescript và Redocly crash hoặc bỏ rơi thao tác âm thầm. Các ref bên ngoài hoặc từ xa (URL http(s)://, hoặc đường dẫn tệp như ./common.yaml#/Address) bị đánh dấu CẢNH BÁO vì công cụ offline này không thể tải về và xác minh — hãy giải chúng trong CI bằng Spectral, Redocly CLI hoặc vacuum. Chỉ số 'Ref đã giải' cho biết bao nhiêu tham chiếu cục bộ trỏ tới thành phần thật, để bạn xác nhận nhanh đồ thị thành phần còn nguyên vẹn. Thủ phạm thường gặp của một ref treo: gõ sai tên thành phần, một schema bạn đổi tên nhưng quên cập nhật, hoặc $ref tới đường dẫn nằm trong tệp khác bạn chưa gói chung.

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.