OpenAPI Visual Designer (API Design in Forms, OpenAPI 3.1 and 3.0)

About the OpenAPI Visual Designer (API Design in Forms, OpenAPI 3.1 and 3.0)

Design an HTTP API the way you think about it — paths, operations, parameters, request bodies, responses, schemas and security — in forms, and its OpenAPI description writes itself beside them in YAML or JSON, as OpenAPI 3.1 or 3.0. Add a resource creates the usual operations in one go (list, create, read, replace, update and delete) with pagination, partial updates as a JSON merge patch and errors as problem details; From an example turns a JSON object into a schema with its types and formats.

Open a Swagger 2.0 or OpenAPI 3.0, 3.1 or 3.2 description to keep working on it: what the forms show becomes editable, and everything else — examples, links, callbacks, webhooks, extensions and schemas with compositions — is kept as written. With a pass the document can also be edited as text, and every change that leaves a valid description goes back into the forms. Every change is checked against the official OpenAPI schemas and common rules, and each problem leads to the form it belongs to. Designs are kept in this browser with Undo, and nothing is uploaded. Without a pass the result is a free preview: the whole API can be designed and checked, and the document shows its first lines; copying and downloading it unlock with a Premium pass.

Common uses

• Designing an API before writing its code (design first), and sharing the description with the people who build and use it.
• Turning a few example JSON payloads into schemas and a consistent set of CRUD endpoints.
• Cleaning up an existing description: renaming schemas, adding missing responses and parameter definitions, and fixing what the checks find.
• Writing the same API as OpenAPI 3.1 and 3.0 for tools that read only one of them.

OpenAPI 3.1 or 3.0?

OpenAPI 3.1 made its Schema Object the same as JSON Schema 2020-12: null is a type of its own (type: [string, "null"]), examples are a list, exclusiveMinimum is a number and a $ref can have a description next to it; it also added webhooks, info.summary and SPDX licence identifiers (the OpenAPI specifications, JSON Schema 2020-12). Many generators and gateways still read only 3.0. The designer keeps your design in 3.1 terms and writes 3.0 by converting it: nullable: true, a single example, boolean exclusive limits and allOf around described references. What 3.0 cannot hold (webhooks, info.summary, a schema that is only null) is left out or kept as it is, and the Checks tab says so.

What a resource gets

A collection path (/orders) with list and create, and an item path (/orders/{orderId}) with read, replace (PUT), update (PATCH) and delete, each with an operationId such as listOrders or createOrder. Creating answers 201 with a Location header; deleting answers 204 without a body (HTTP semantics, RFC 9110). Updates are JSON merge patches: members left out stay as they are and null removes one (RFC 7396). The list is paged with limit and offset, page and pageSize, or an opaque cursor. Errors are problem details with type, title, status, detail and instance (RFC 9457). The id is read-only, so it is sent by the server and not expected in requests.

Opening a description you already have

Swagger 2.0 and OpenAPI 3.0 are upgraded with the same conversion as the OpenAPI Editor, so the design is always in 3.1 terms; a 3.0 description stays set to be written as 3.0. Parameters, bodies, responses and schemas the forms can show become editable. Everything else is kept exactly as written and written back: $refs to shared parameters and responses, examples, links, headers, callbacks, webhooks, server variables, x- extensions, and schemas with oneOf, allOf, conditionals or other keywords the grid does not show (they open as JSON you can edit). OpenAPI 3.2 is designed and written as 3.1; members that are new in 3.2 are kept, and the checks point them out.

The checks

Each change is checked twice: by the designer, for things the forms can point at (a {parameter} in a path with no definition, the same method twice on a path, two schemas with one name), and by the OpenAPI Editor’s validator against the official OpenAPI schema of the version you chose, with its rules for operationIds, path parameters and references. Choosing a problem opens the form where it can be fixed.

Limitations

• Descriptions of up to 10 MB can be opened; a design is kept in this browser up to about 600 KB of text (larger ones stay on the page until it is closed).
• The forms show the first media type of each body and response; other media types, encodings and examples are kept as written.
• Schemas with compositions (oneOf, anyOf, allOf), conditionals or tuple items open as JSON rather than in the member grid.
• One description per design: references to other files are kept as written but not followed.
• Comments in an opened YAML file are not kept: the document is written fresh from the design.

Privacy

On this device: nothing is sent

Everything happens in your browser. What you enter or open here is not uploaded or stored by MySmartCoPilot.