JSON SchemaCông cụ OpenAPIchuyển đổi trực tuyến
Việc chuyển đổi mô hình dữ liệu giữa các tiêu chuẩn khác nhau có thể là một công việc thủ công tốn nhiều thời gian. Công cụ chuyển đổi của chúng tôi JSON Schematự OpenAPIđộng hóa quy trình này, cho phép bạn chuyển đổi JSON Schemacác định nghĩa tiêu chuẩn thành các định dạng tương thích OpenAPIvới Đặc tả OAS(OAS) ngay lập tức. Cho dù bạn đang xây dựng tài liệu Swagger hay định nghĩa nội dung yêu cầu/phản hồi, công cụ này đều đảm bảo tính chính xác và tuân thủ.
Tại sao nên chuyển đổi JSON Schemasang OpenAPI?
Mặc dù OpenAPI(trước đây là Swagger) sử dụng một tập hợp con của JSON Schema, nhưng có những khác biệt quan trọng trong cách xử lý một số từ khóa nhất định như type, nullable, và formatgiữa các phiên bản khác nhau(Bản nháp 4, 7 hoặc 2019-09) và OpenAPIcác thông số kỹ thuật 3.0/3.1.
Thu hẹp khoảng cách về khả năng tương thích
OpenAPIPhiên bản 3.0 có những ràng buộc cụ thể khác với phiên bản tiêu chuẩn JSON Schema. Công cụ chuyển đổi của chúng tôi xử lý những điểm khác biệt này, chẳng hạn như chuyển đổi dependenciessang logic tương thích hoặc điều chỉnh typemảng để đáp ứng OpenAPIcác yêu cầu nghiêm ngặt của phiên bản 3.0, đảm bảo tài liệu API của bạn vẫn hợp lệ.
Tối ưu hóa quá trình phát triển API
Thay vì viết lại các mô hình cơ sở dữ liệu hoặc lược đồ xác thực cho tài liệu API của bạn, bạn chỉ cần sao chép những gì đã có JSON Schema. Điều này giúp giảm thiểu lỗi do con người và giữ cho logic phía máy chủ và tài liệu luôn đồng bộ hoàn hảo.
Các tính năng chính của công cụ chuyển đổi của chúng tôi
Công cụ của chúng tôi được thiết kế dành cho các nhà phát triển cần độ chính xác và tốc độ khi quản lý các thông số kỹ thuật API.
1. Hỗ trợ nhiều JSON Schemabản nháp
Cho dù lược đồ nguồn của bạn dựa trên bản nháp 4, 7 hay 2020-12, công cụ của chúng tôi đều xác định cấu trúc và ánh xạ nó đến OpenAPIcấu trúc tương đương gần nhất.
2. OpenAPI3.0 & 3.1 Sẵn sàng
OpenAPIPhiên bản 3.1 hiện đã hoàn toàn tương thích với JSON Schemaphiên bản 2019-09. Tuy nhiên, nếu bạn vẫn đang sử dụng phiên OpenAPIbản 3.0, công cụ của chúng tôi sẽ tự động "hạ cấp" một số trường cụ thể(ví dụ như nullable: truethay vì type: ["string", "null"]) để duy trì khả năng tương thích.
3. Xác thực và định dạng tức thì
Nó không chỉ chuyển đổi dữ liệu mà còn làm đẹp kết quả đầu ra. Bạn sẽ nhận được một OpenAPIlược đồ sạch sẽ, được thụt lề và hợp lệ, sẵn sàng để dán vào components/schemasphần của mình.
Hướng dẫn sử dụng công cụ chuyển đổi
Dán mã của bạn: Sao chép mã nguồn JSON Schemavào trình soạn thảo nhập liệu.
Chọn phiên bản(Tùy chọn): Chọn xem bạn muốn tối ưu hóa đầu ra cho chuẩn OpenAPI3.0 hay chuẩn 3.1 mới hơn.
Nhấp vào Chuyển đổi: Công cụ sẽ xử lý logic và hiển thị kết quả tuân thủ OpenAPI trong cửa sổ đầu ra.
Sao chép & Sử dụng: Sử dụng nút "Sao chép" để lấy lược đồ mới cho tài liệu Swagger hoặc Redocly của bạn.
Những khác biệt kỹ thuật cần lưu ý
Xử lý thuộc tính "Nullable"
Trong phiên bản chuẩn JSON Schema, một trường có thể rỗng thường được định nghĩa là `null` type: ["string", "null"]. Trong OpenAPIphiên bản 3.0, điều này phải được chuyển đổi thành `null` type: stringbằng một nullable: truethuộc tính riêng biệt. Trình chuyển đổi của chúng tôi xử lý việc này tự động.
Từ khóa "định dạng"
OpenAPIsử dụng formattừ khóa này rộng rãi hơn để xác thực(ví dụ: int32, int64, float, double). Công cụ của chúng tôi đảm bảo rằng các định dạng này được bảo toàn và ánh xạ chính xác trong quá trình chuyển đổi.
Câu hỏi thường gặp(FAQ)
Bộ chuyển đổi này có tương thích với Swagger 2.0 không?
Mặc dù trọng tâm là phiên bản OpenAPI3.x, nhưng các lược đồ được tạo ra phần lớn tương thích với Swagger 2.0, mặc dù definitionscó thể cần một số điều chỉnh cho phần này.
Dữ liệu của tôi có bị rời khỏi trình duyệt không?
Không. Toàn bộ logic chuyển đổi diễn ra cục bộ trong trình duyệt của bạn bằng JavaScript. Các lược đồ API nhạy cảm của bạn không bao giờ được gửi đến máy chủ của chúng tôi.
Tôi có thể chuyển đổi các lược đồ lớn và phức tạp không?
Đúng vậy. Công cụ của chúng tôi được tối ưu hóa để xử lý các lược đồ lồng nhau sâu và các định nghĩa đối tượng lớn mà không gây ra hiện tượng giảm hiệu năng.