What OpenAPI version does this produce?

It emits an OpenAPI 3.0.3 document, the most widely supported version across Swagger UI, code generators, and API gateways. The top openapi field declares 3.0.3 so tools parse it correctly.

How are the collection and item paths structured?

The builder generates a collection path like /users for GET list and POST create, and an item path like /users/{id} for GET one, PUT update, and DELETE. The id path parameter is declared as a required string.

Where are the data models defined?

Reusable models live under components.schemas and are referenced with a $ref pointer. The stub includes a sample object schema and an Error schema, so request bodies and responses both point at named components instead of inline duplicates.

How does the security scheme work?

A bearer scheme is declared under components.securitySchemes as type http with the bearer scheme, while an API-key scheme uses type apiKey in the header. A top-level security array then applies it to every operation by default.

Can I import this straight into Swagger UI?

Yes. Paste the YAML into editor.swagger.io and it renders interactive docs immediately. Because it is valid OpenAPI 3.0, you can also feed it to client and server code generators or mock-server tools.

OpenAPI / Swagger Stub Builder

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

Starting an API spec from a blank file is tedious. This builder generates a valid OpenAPI 3.0 stub for a single resource — with collection and item paths, request and response schemas, and an optional auth scheme — so you can open it in Swagger UI and start documenting immediately.

How it works

The document follows the OpenAPI 3.0 structure: an openapi version, an info block, a servers list, paths, and reusable components. List and create operations live on the collection path, while fetch-one, update, and delete live on the item path with a typed id parameter:

paths:
  /users:
    get: { summary: List users, responses: { "200": ... } }
    post: { summary: Create user, requestBody: ... }
  /users/{id}:
    get: { parameters: [ { name: id, in: path, required: true } ] }

Data models are declared once under components.schemas and referenced via $ref: "#/components/schemas/User", so request bodies and responses share a single definition. A security scheme under components.securitySchemes plus a top-level security array applies bearer or API-key auth to every operation.

Tips and notes

Rename the sample fields under the resource schema to match your real model, and add more properties as needed. Paste the result into editor.swagger.io for a live preview, or feed it to a code generator to scaffold typed clients and server stubs. Keep the Error schema — consistent error shapes make a generated client far easier to consume.