Create OpenAPI (Swagger) Schemas from JSON

What is the OpenAPI Specification (OAS)?

The OpenAPI Specification (OAS) is a standard, language-independent interface description for RESTful APIs. Previously known as “Swagger,” it is now maintained as a community-driven open project.

Written in either YAML or JSON, OAS has become an essential part of automating modern development workflows:

• Interactive Documentation: Auto-generate documentation with tools like Swagger UI.
• Client Code Generation: Automatically output SDKs (libraries) for various programming languages.
• Mock Server Construction: Build dummy servers to allow frontend development to proceed in parallel.
• Quality Control: Validate request and response schemas to ensure protocol compliance.

The Challenge of “Nested” Schema Definitions

When building API specifications, the most time-consuming task is often defining the “Schema” for request and response bodies.

Manually writing out OpenAPI structures (type, properties, required, items, etc.) for deeply nested objects or JSON with dozens of properties is not only slow but also prone to simple human errors.

Efficient Auto-Generation from JSON

If you already have a working API or a sample JSON response, the most efficient approach is to generate the schema automatically.

1. Get the JSON data from an actual API call.
2. Paste the JSON into our JSON to OpenAPI Generator.
3. Get the output in components/schemas format within seconds.
4. Integrate the generated definition into your main openapi.yaml file.

Features of Our Tool

The DevToolKits generator operates based on the latest OpenAPI 3.1.0 standards.

• Type Inference: Accurately distinguishes between numbers, strings, booleans, objects, and arrays.
• Required Field Extraction: Automatically lists properties found in the JSON as required (can be adjusted later).
• Type Integration (oneOf): Uses oneOf to comprehensively express multiple types if they are mixed within an array.
• Date Format Detection: Automatically adds format: date-time when strings like 2024-01-15T12:00:00Z are detected.
• OpenAPI 3.1 Compliance: Optimized for the latest specification, such as using type: "null" instead of nullable: true.

💡 Pro Hint: Auto-generation gives you a “draft.” After generating the schema, polish it into a user-friendly document by adding description and example tags to each property for your team members and API consumers.