OpenAPI Viewer

about this tool

Read an API description

Paste an OpenAPI document — or open a .yaml or .json file — and it is laid out as the API it describes. The title, version and servers come first, with any server variables filled in by their defaults. Then every operation, grouped under a tag in the order the document lists its tags: the method, the path and the summary, opening onto its description, its parameters, its request body, each response by status code, what authentication it needs, and a curl command to start from. Search by method, path, summary, operationId or tag — every word has to match — or pick one tag. The named schemas are listed at the end, each opening into a tree of its properties.

Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1 are all read, and the older shape is turned into the newer one as it is read: Swagger's host, base path and schemes become server URLs (https when no scheme is given, and only the base path when there is no host), a body or form parameter becomes the request body, and a file upload becomes a binary string. Parameters set on the path are merged into each of its operations, an operation's own parameter replacing a path-level one with the same name and location, as the specification says; servers set on a path or an operation are used for its curl command. Descriptions are shown as plain text with their line breaks kept, and Markdown in them is not rendered.

YAML is read as YAML 1.2, with merge keys (<<) expanded because API documents use them, and a duplicate key is an error in YAML and in JSON alike. Webhooks and callbacks are counted but not drawn.

References and schemas

References inside the document are followed as JSON Pointers, by the rules of RFC 6901: ~1 is a slash, ~0 a tilde, and a percent-encoded fragment is decoded first. In 3.1, a description written beside a reference replaces the one it points at, as does a schema's title, description, default, examples or read-only and write-only flags. A schema is shown as a tree — the properties of an object, the items of an array, and each part of a oneOf, anyOf, allOf or not — with its type and format, whether it is required or nullable, and its constraints: enum values, constants, bounds, lengths, patterns, item counts, defaults, read-only and write-only. A schema that refers back to itself, like a comment with replies that are comments, is marked where the loop closes instead of being opened for ever, and a schema that branches so widely it would take thousands of lines stops and says so. Both 3.0's nullable: true and 3.1's type: [string, "null"] read as nullable.

Example bodies are shown for JSON, and come from the document where it gives them — the media type's example or the first inline examples value, then the schema's example, the first of its examples, a const, a default or the first enum value — and otherwise from placeholders by type and format, a number respecting its minimum. In an example, properties from every part of an allOf are merged into one object, a oneOf or anyOf takes its first choice, read-only properties are left out of a request and write-only ones out of a response.

Problems

Alongside the operations, the viewer lists where the document breaks the specification's requirements: a missing info, title or version; no paths (in 3.1, none of paths, webhooks or components); a path without its leading slash; a {parameter} in a path with no path parameter to match it, a path parameter the path does not contain or one not marked required; two paths that are the same apart from their parameter names; a parameter listed twice in one list; an operationId used by two operations; an operation with no responses; a response keyed by something that is not a status code, a range such as 4XX, or default; in Swagger 2.0, more than one body parameter or a body with form parameters; a security scheme that is asked for but never defined; and any reference that points at nothing. References to other files and anchor-style references are listed where they are used, since a pasted document cannot follow them. It checks structure, not every field, so a clean list does not make a document valid — a full validator does that.

Limits

Only one document is read: nothing is fetched — not other files, not servers, not example URLs. The viewer reads a file up to 10 MB, or about ten million characters pasted, and refuses a document nested more than 400 levels deep. The JSON copy of a YAML document loses its comments and anchors, and whole numbers beyond 2^53 are rounded, as JavaScript reads them. OpenAPI 3.1 describes bodies with JSON Schema, and 2.0 and 3.0 with a close variant of it; to check a real payload against a schema, the JSON Schema validator does that. Nothing leaves the page.

questions

Which versions of OpenAPI does it read?

Swagger 2.0 and OpenAPI 3.0 and 3.1, as YAML or JSON. Swagger 2.0 keeps its server as host, basePath and schemes, and its request body as a body or formData parameter; the viewer turns both into the 3.x shape, so every version reads the same way. A document marked 3.2 or any later 3.x is read as 3.1, with a note that anything newer is not shown.

What problems does it find in a spec?

The structural rules the specification states as requirements: info with a title and version, paths that begin with a slash, every {parameter} in a path declared as a required path parameter and no path parameter the path lacks, no two paths that differ only in their parameter names, no parameter listed twice in one list, unique operationIds, at least one response keyed by a status code, a range such as 4XX or default, security schemes that exist, and references that point at something. It is not a full validator of every field and value.

Does it follow $ref references?

References within the document, yes, by JSON Pointer as RFC 6901 defines it, including the ~0 and ~1 escapes and percent-encoded fragments; a schema that refers back to itself is marked where the loop closes rather than expanded forever. A reference to another file, such as schemas.yaml#/Pet, cannot be followed from pasted text, so it is listed as a problem at the place it is used instead of being fetched.

Where do the example bodies and curl commands come from?

From the document where it gives them — an example, the first of examples, a const, a default or the first enum value — and otherwise from placeholders by type and format, such as a fixed date for date-time and 0, or the minimum, for an integer. Read-only fields are left out of requests. The curl command uses the operation’s server, fills in required query parameters, headers and cookies, and adds a JSON or form body; authentication is left for you to add.

Is my API description uploaded anywhere?

No. The document is parsed and drawn in your browser, and nothing it references is fetched — not other files, not servers, not example URLs. That makes it safe for an internal API that is not published anywhere.