How is this different from the OpenAPI Validator?

The OpenAPI Validator checks a spec you already have (or wrote by hand) for structural mistakes. This tool does the opposite: it builds a brand-new, valid OpenAPI 3.1 document from a list of paths and a schema fragment, when you don't have a spec yet.

What goes in the schema fragment field?

A JSON Schema fragment (the same subset OpenAPI schemas use: type, properties, items, required, and so on) describing that path's request/response body shape. It's parsed as JSON and inserted directly into both the 200 response schema and, for POST/PUT/PATCH methods, the requestBody schema.

What does the auth scheme toggle actually add to the spec?

Choosing apiKey adds a components.securitySchemes.ApiKeyAuth definition (an API key sent as an X-API-Key header) and applies it to every generated operation's security field; choosing bearer does the same with an HTTP bearer scheme instead. Choosing none omits security entirely.

Can I leave the schema fragment blank for a path?

Yes. A path with no schema still generates a valid operation with a 200 response, just without a response body schema or (for write methods) a requestBody, useful for simple endpoints that don't return or accept a structured body.

OpenAPI Generator - Build a Full OpenAPI 3.1 Spec

Overview

Introduction

Writing an OpenAPI document by hand means getting a lot of nested YAML structure exactly right: the paths object, per-method operations, response wrappers, and security scheme definitions.

This tool builds that structure directly from a plain list of paths and schema fragments, generating a complete, valid OpenAPI 3.1 document in your browser.

What Is OpenAPI Generator?

An OpenAPI 3.1 document generator that assembles info, servers, paths, components, and security sections from repeatable path rows and an auth scheme choice.

It's part of this site's API Tools collection, and complements the existing OpenAPI Validator (which checks a spec you already have) and OpenAPI Example Payload Generator (which derives one example from a schema fragment) rather than replacing either.

How OpenAPI Generator Works

Each path row's schema fragment is parsed as JSON and attached as the schema for that operation's 200 response, and additionally as the requestBody schema for POST/PUT/PATCH methods, since those methods conventionally accept a body of the same shape they return.

The chosen auth scheme (none/apiKey/bearer) is translated into an OpenAPI securityScheme definition under components and referenced from every generated operation's security array, and the whole document is serialized with a YAML library so indentation and structure are always correct.

When To Use OpenAPI Generator

Use it when starting a brand-new API and you want a valid OpenAPI document to iterate on, rather than assembling the YAML structure by hand from a blank file.

It's also useful for quickly scaffolding a spec for a small internal service where writing full API documentation from scratch would otherwise take longer than the service itself.

Often used alongside Swagger YAML Generator, Postman Collection Generator and REST API Config Generator.

Features

Advantages

Generates syntactically valid OpenAPI 3.1 YAML through a real YAML serializer, avoiding hand-indentation mistakes.
Wires up request and response schemas together from a single schema fragment per path, rather than requiring both to be specified separately.
Adds a working security scheme definition and applies it consistently across every operation when an auth scheme is selected.

Limitations

Uses the same schema fragment for both a path's request and response bodies; if they genuinely differ, generate the document first and then hand-edit the divergent one.
Doesn't extract shared schemas into named components.schemas definitions; every schema is inlined directly into its operation.
Doesn't model multiple response status codes per operation; only a single 200 response is generated.

Examples

A single GET path with an apiKey auth scheme

Input

title: "Widgets API", version: "1.0.0", serverUrl: "https://api.example.com/v1", authScheme: apiKey, paths: [{method: get, path: /widgets, summary: "List widgets", schema: {"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"}}}}}]

Output

openapi: 3.1.0
info:
  title: Widgets API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /widgets:
    get:
      summary: List widgets
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

The GET operation gets a 200 response using the provided array schema, and its security array references the generated ApiKeyAuth scheme.

Best Practices & Notes

Best Practices

Paste a fully-formed JSON Schema fragment (not a partial one missing type) for each path so the generated response/request bodies are actually useful to downstream tooling.
Run the generated document through the OpenAPI Validator afterward as a sanity check, especially after any manual edits.
Extract genuinely shared schemas into components.schemas by hand afterward if several paths return the same shape, to avoid repeating large inline schemas.

Developer Notes

YAML serialization is done with the `yaml` package's `stringify()` rather than hand-built string templates, so nested schema objects of arbitrary depth are always emitted with syntactically correct indentation; each path row's schema is parsed independently with its own try/catch so one malformed fragment reports a specific, attributable error rather than failing the whole generation silently.

OpenAPI Generator Use Cases

Scaffolding a first-draft OpenAPI document for a new internal or public API
Generating a spec skeleton to hand off to a code-generation tool (client SDKs, server stubs) that requires OpenAPI input
Producing a quick, valid example OpenAPI document for documentation or teaching purposes

Common Mistakes

Assuming request and response bodies are always identical; this generator uses one schema for both, which is a simplification you may need to split apart by hand afterward.
Pasting a schema fragment that isn't valid JSON (like one with trailing commas or single-quoted keys), which is rejected with a per-path error rather than silently ignored.

Tips

If a path doesn't need a body at all (like a DELETE by ID), leave its schema fragment blank rather than pasting an empty object; the generator omits the schema-dependent fields cleanly in that case.

OpenAPI Generator