Bộ công cụ OpenAPI / Swagger

Q: Chuyển đổi Swagger 2.0 không xử lý được gì?

schemes riêng cho từng operation, collection format tsv và allowEmptyValue trên trường form không có tương đương trong OpenAPI 3.0 nên bị bỏ; bản chuyển đổi liệt kê từng trường hợp gặp phải. Tham chiếu bên ngoài được giữ nguyên.

Mở một đặc tả OpenAPI 3.0 / 3.1 hoặc Swagger 2.0 ở dạng JSON hay YAML và làm mọi việc tại một chỗ: duyệt từng endpoint theo tag, kiểm tra lỗi cấu trúc, so sánh hai phiên bản để tìm thay đổi phá vỡ tương thích, và xuất ra — chuyển sang OpenAPI 3.0, tài liệu Markdown hoặc HTML độc lập, ví dụ cURL hay kiểu TypeScript.

Các bước sử dụng

Dán đặc tả vào ô Đặc tả (JSON hoặc YAML), hoặc bấm Mở tệp để chọn tệp .json, .yaml, .yml. Mẫu 3.0 (YAML) và Mẫu 2.0 (JSON) nạp sẵn đặc tả Petstore nhỏ để thử.
Ở thẻ Trình xem, endpoint được nhóm theo tag, có nhãn method tô màu. Thu hẹp danh sách bằng ô tìm kiếm, Mọi method và Mọi tag. Mở một endpoint để xem Tham số, Body của request, Phản hồi theo mã trạng thái và lệnh cURL dựng sẵn. Danh sách schema liệt kê mọi schema trong components.
Mở thẻ Kiểm tra để xem danh sách vấn đề kèm mức độ và JSON pointer ở cột Vị trí. Chuyển giữa Lỗi và Cảnh báo để tập trung.
Mở thẻ So sánh, dán đặc tả mới hơn vào Phiên bản mới (B) (hoặc bấm Chép A sang B rồi sửa), sau đó đọc phần tổng hợp thêm / xóa / thay đổi. Bật Chỉ thay đổi phá vỡ để chỉ xem những thay đổi có thể làm hỏng client đang dùng.
Mở thẻ Chuyển đổi & xuất, chọn định dạng đầu ra rồi Sao chép hoặc Tải xuống. Với → OpenAPI 3.0, JSON và YAML, nút Dùng làm đầu vào nạp kết quả ngược lại vào ô soạn thảo. Tài liệu HTML có công tắc Xem trước.

Mẹo

Chỉ các $ref cục bộ (#/components/..., #/definitions/...) được phân giải. Schema tự tham chiếu như cây danh mục hiển thị là (circular) thay vì lặp vô hạn. Ref bên ngoài (common.yaml#/Pet, URL) được liệt kê thành cảnh báo và không bao giờ bị tải về.
Tài liệu Swagger 2.0 được hiển thị ở Trình xem, so sánh ở So sánh và xuất ra thông qua bản chuyển đổi sang OpenAPI 3.0, còn Kiểm tra luôn kiểm tra đúng tài liệu bạn viết để mọi pointer khớp với văn bản gốc.
Các kiểm tra gồm: trường bắt buộc ở cấp cao nhất theo từng phiên bản, đường dẫn bắt đầu bằng /, biến {id} trong đường dẫn phải được khai báo in: path kèm required: true, trùng operationId hoặc trùng tham số, phản hồi thiếu description, method HTTP không hợp lệ, ref cục bộ bị hỏng, tham số thiếu schema/content (3.x) hoặc type (2.0), dạng URL máy chủ và biến máy chủ chưa khai báo, host/basePath (2.0), yêu cầu bảo mật trỏ tới cơ chế chưa định nghĩa, và tag được dùng nhưng chưa khai báo (cảnh báo).
So sánh ghép endpoint theo method + đường dẫn và bỏ qua tên biến, nên /pets/{id} và /pets/{petId} được coi là cùng một endpoint. Thay đổi phá vỡ gồm: xóa endpoint, tham số, mã phản hồi hay thuộc tính; thêm tham số hoặc thuộc tính request bắt buộc; tham số trở thành bắt buộc; đổi kiểu; và thuộc tính phản hồi không còn bắt buộc.
Chuyển 2.0 → 3.0 ánh xạ host + basePath + schemes thành servers, definitions thành components.schemas (viết lại mọi pointer), tham số body và formData thành requestBody (dùng multipart khi có trường type: file), consumes/produces thành media type, collectionFormat thành style/explode, x-nullable thành nullable và securityDefinitions thành components.securitySchemes.
Ví dụ cURL lấy giá trị từ example, default hoặc phần tử enum đầu tiên, nếu không có thì dùng giá trị giữ chỗ theo kiểu hoặc format. Cơ chế bảo mật thêm các chỗ giữ như <TOKEN> để bạn thay.
Đầu ra TypeScript biến schema object thành interface (allOf gồm các ref thành extends), enum thành union chuỗi, nullable hoặc kiểu "null" thành | null, oneOf/anyOf thành union và additionalProperties thành Record<string, T>.

Sửa đặc tả lớn vẫn mượt: tài liệu chỉ được phân tích lại khi bạn ngừng gõ, và chi tiết endpoint chỉ được dựng khi bạn mở ra.

Câu hỏi thường gặp

Đặc tả của tôi có bị tải lên đâu không?

Không. Phân tích, kiểm tra, so sánh và mọi định dạng xuất đều chạy trong trình duyệt của bạn. Không có gì được gửi lên máy chủ, và $ref bên ngoài không bao giờ bị tải về.

Tệp HTML xuất ra có an toàn để đưa lên web không?

Có. Đó là một tệp độc lập, CSS viết sẵn bên trong và hoàn toàn không có script. Mọi đoạn văn bản lấy từ đặc tả đều được escape, chỉ giữ liên kết http(s) và mailto, và thẻ Content-Security-Policy chặn script như một lớp bảo vệ thứ hai.

Chuyển đổi Swagger 2.0 không xử lý được gì?

schemes riêng cho từng operation, collection format tsv và allowEmptyValue trên trường form không có tương đương trong OpenAPI 3.0 nên bị bỏ; bản chuyển đổi liệt kê từng trường hợp gặp phải. Tham chiếu bên ngoài được giữ nguyên.

Kiểm tra có phải là kiểm tra JSON Schema đầy đủ không?

Không. Đây là bộ kiểm tra cấu trúc viết thủ công, nhắm vào những lỗi làm hỏng trình sinh code và công cụ tài liệu. Một tài liệu không có cảnh báo nào vẫn có thể chứa giá trị mà schema chính thức từ chối.

Hướng dẫn liên quan — Lập Trình

Bộ công cụ OpenAPI / Swagger

Các bước sử dụng

Dán đặc tả vào ô Đặc tả (JSON hoặc YAML), hoặc bấm Mở tệp để chọn tệp .json, .yaml, .yml. Mẫu 3.0 (YAML) và Mẫu 2.0 (JSON) nạp sẵn đặc tả Petstore nhỏ để thử.

Ở thẻ Trình xem, endpoint được nhóm theo tag, có nhãn method tô màu. Thu hẹp danh sách bằng ô tìm kiếm, Mọi method và Mọi tag. Mở một endpoint để xem Tham số, Body của request, Phản hồi theo mã trạng thái và lệnh cURL dựng sẵn. Danh sách schema liệt kê mọi schema trong components.

Mở thẻ Kiểm tra để xem danh sách vấn đề kèm mức độ và JSON pointer ở cột Vị trí. Chuyển giữa Lỗi và Cảnh báo để tập trung.

Mở thẻ So sánh, dán đặc tả mới hơn vào Phiên bản mới (B) (hoặc bấm Chép A sang B rồi sửa), sau đó đọc phần tổng hợp thêm / xóa / thay đổi. Bật Chỉ thay đổi phá vỡ để chỉ xem những thay đổi có thể làm hỏng client đang dùng.

Mở thẻ Chuyển đổi & xuất, chọn định dạng đầu ra rồi Sao chép hoặc Tải xuống. Với → OpenAPI 3.0, JSON và YAML, nút Dùng làm đầu vào nạp kết quả ngược lại vào ô soạn thảo. Tài liệu HTML có công tắc Xem trước.

Mẹo

Chỉ các $ref cục bộ (#/components/..., #/definitions/...) được phân giải. Schema tự tham chiếu như cây danh mục hiển thị là (circular) thay vì lặp vô hạn. Ref bên ngoài (common.yaml#/Pet, URL) được liệt kê thành cảnh báo và không bao giờ bị tải về.

Tài liệu Swagger 2.0 được hiển thị ở Trình xem, so sánh ở So sánh và xuất ra thông qua bản chuyển đổi sang OpenAPI 3.0, còn Kiểm tra luôn kiểm tra đúng tài liệu bạn viết để mọi pointer khớp với văn bản gốc.

Các kiểm tra gồm: trường bắt buộc ở cấp cao nhất theo từng phiên bản, đường dẫn bắt đầu bằng /, biến {id} trong đường dẫn phải được khai báo in: path kèm required: true, trùng operationId hoặc trùng tham số, phản hồi thiếu description, method HTTP không hợp lệ, ref cục bộ bị hỏng, tham số thiếu schema/content (3.x) hoặc type (2.0), dạng URL máy chủ và biến máy chủ chưa khai báo, host/basePath (2.0), yêu cầu bảo mật trỏ tới cơ chế chưa định nghĩa, và tag được dùng nhưng chưa khai báo (cảnh báo).

So sánh ghép endpoint theo method + đường dẫn và bỏ qua tên biến, nên /pets/{id} và /pets/{petId} được coi là cùng một endpoint. Thay đổi phá vỡ gồm: xóa endpoint, tham số, mã phản hồi hay thuộc tính; thêm tham số hoặc thuộc tính request bắt buộc; tham số trở thành bắt buộc; đổi kiểu; và thuộc tính phản hồi không còn bắt buộc.

Chuyển 2.0 → 3.0 ánh xạ host + basePath + schemes thành servers, definitions thành components.schemas (viết lại mọi pointer), tham số body và formData thành requestBody (dùng multipart khi có trường type: file), consumes/produces thành media type, collectionFormat thành style/explode, x-nullable thành nullable và securityDefinitions thành components.securitySchemes.

Ví dụ cURL lấy giá trị từ example, default hoặc phần tử enum đầu tiên, nếu không có thì dùng giá trị giữ chỗ theo kiểu hoặc format. Cơ chế bảo mật thêm các chỗ giữ như <TOKEN> để bạn thay.

Đầu ra TypeScript biến schema object thành interface (allOf gồm các ref thành extends), enum thành union chuỗi, nullable hoặc kiểu "null" thành | null, oneOf/anyOf thành union và additionalProperties thành Record<string, T>.