OpenAPI support
What oaspect reads from your document, how it shows it, and the extensions it understands.
Versions and formats
- OpenAPI 3.0 and 3.1, as JSON or YAML.
- Swagger 2.0, converted to OpenAPI 3.0 on load:
definitions,parametersandresponsesmove tocomponents,bodyandformDataparameters become request bodies,host/basePath/schemesbecomeservers,securityDefinitionsbecome security schemes. - The document must have
openapi(orswagger) andpaths.
References
- Local
$refs (#/components/schemas/Pet) anywhere, including cycles, which are shown once and marked. - External references to other files and URLs (
./schemas/pet.yaml,common.json#/Error,https://…) resolve relative to the document's URL. WithspecUrlthe browser fetches them (same origin, or with CORS); the CLI reads them from disk. A document with up to 100 referenced files is supported.
What is shown
| OpenAPI | In the reference |
|---|---|
info | Title, version, Markdown description, a contact link when contact.email is set; counts of operations, tags and models |
servers, server variables | The Connection panel: server picker and variable inputs, applied to Try and samples |
tags | Navigation groups, with descriptions; operations without tags go under "Default" |
| Operations | Method, path, summary, description, operationId, deprecation, required security |
| Parameters | Path, query, header and cookie, with type, required, default, enum, constraints, examples, deprecation |
| Request bodies | Every media type; schema tree and example for each |
| Responses | Status, description, headers, schema tree and examples per media type; links to other operations |
callbacks | Shown under their operation, each with its request and responses |
webhooks (3.1) | A Webhooks section, each with its payload and the responses your server should send |
components.schemas | The Models section, one entry per schema |
securitySchemes | The Connection panel inputs; see Try it |
Schemas
Schema trees expand field by field and show:
$ref(linked by name to its model),allOf(merged into one object),oneOfandanyOf(one tab per variant);- arrays, maps (
additionalProperties), nested objects, and 3.1 type arrays (["string", "null"]shows asstring | null); required,nullable,readOnly,writeOnlyanddeprecatedflags;formatin the type (string<uuid>),enumvalues,default,example,pattern, minimum and maximum (exclusive too),multipleOf, lengths, item counts anduniqueItems.
Examples
Request and response examples come from the media type's example or examples (with a picker when there are several), else they are generated from the schema. For each field the generator takes, in order: example, the first of examples, default, the first enum value, const, the first oneOf/anyOf variant, and otherwise a value for the type: a sample for the format (date-time, email, uuid, uri…), the minimum for numbers, true for booleans. writeOnly properties are left out.
Guide sections
Not everything is an endpoint. A WebSocket protocol, a webhook signature scheme or an integration walkthrough needs headings and prose, and oaspect lays them out the way Redoc does:
- Headings in
info.descriptionbecome entries of their own in the navigation, after "Introduction". The shallowest heading level gives the entries; the next level is listed under them when the entry opens. - Tags without operations are guide sections: a title in the navigation and the tag's Markdown
description, in the order oftags. Their headings are listed under the title the same way. - Tags with operations list their description's headings before the operations.
x-traitTag: truemakes a tag a guide section even when operations use it; those operations stay listed under their other tags.
tags:
- name: WebSocket session
description: |
## Connecting {#connecting}
Open `wss://api.example.com/ws?session={id}`.
## Messages {#messages}
Every frame is a JSON object with a `type`.
### Client to server {#client-messages}
…
- name: Documents
description: Identity document checks over HTTP.
paths:
/documents:
post:
tags: [Documents]Every listed heading is an anchor: #introduction/<heading> in the description, #tag/<tag>/<heading> in a tag, so you can link straight to it. The anchor comes from the heading text; add {#id} at the end of the heading to fix it, which keeps links working when the text changes or is translated.
Markdown
Descriptions are Markdown (a GitHub-flavored subset): headings (with an optional {#id}), paragraphs, emphasis, strikethrough, inline code, links, images, automatic links, ordered, unordered and task lists, nested lists, tables with alignment, fenced code blocks (highlighted for the languages oaspect knows), block quotes and horizontal rules.
Raw HTML is never rendered: it shows as text. Links and images accept http, https, mailto and relative URLs only.
Extensions
| Extension | Where | Purpose |
|---|---|---|
x-i18n | Most objects with text | Translations of summary, description, title and tag name. See Localization. |
:::lang blocks | Markdown text | Several languages in one field. See Localization. |
x-traitTag | Tag | true shows the tag as a guide section only. See Guide sections. |
{#id} | Markdown heading | Fixed anchor for the heading. |
Other x- extensions are ignored. oaspect stores resolved external documents under components.x-oaspect-external; you never write that yourself.
Not supported yet
- XML schemas (
xmlobjects) are shown as plain schemas. constanddiscriminatorare not shown;x-codeSamples(Redoc's custom samples) andx-tagGroupsare ignored.- Headings deeper than
###are not listed in the navigation. - OAuth2
authorizationCodeandimplicitflows take a token obtained elsewhere; there is no redirect flow.