Reference

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, parameters and responses move to components, body and formData parameters become request bodies, host/basePath/schemes become servers, securityDefinitions become security schemes.
  • The document must have openapi (or swagger) and paths.

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. With specUrl the 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

OpenAPIIn the reference
infoTitle, version, Markdown description, a contact link when contact.email is set; counts of operations, tags and models
servers, server variablesThe Connection panel: server picker and variable inputs, applied to Try and samples
tagsNavigation groups, with descriptions; operations without tags go under "Default"
OperationsMethod, path, summary, description, operationId, deprecation, required security
ParametersPath, query, header and cookie, with type, required, default, enum, constraints, examples, deprecation
Request bodiesEvery media type; schema tree and example for each
ResponsesStatus, description, headers, schema tree and examples per media type; links to other operations
callbacksShown 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.schemasThe Models section, one entry per schema
securitySchemesThe 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), oneOf and anyOf (one tab per variant);
  • arrays, maps (additionalProperties), nested objects, and 3.1 type arrays (["string", "null"] shows as string | null);
  • required, nullable, readOnly, writeOnly and deprecated flags;
  • format in the type (string<uuid>), enum values, default, example, pattern, minimum and maximum (exclusive too), multipleOf, lengths, item counts and uniqueItems.

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.description become 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 of tags. Their headings are listed under the title the same way.
  • Tags with operations list their description's headings before the operations.
  • x-traitTag: true makes a tag a guide section even when operations use it; those operations stay listed under their other tags.
yaml
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

ExtensionWherePurpose
x-i18nMost objects with textTranslations of summary, description, title and tag name. See Localization.
:::lang blocksMarkdown textSeveral languages in one field. See Localization.
x-traitTagTagtrue shows the tag as a guide section only. See Guide sections.
{#id}Markdown headingFixed 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 (xml objects) are shown as plain schemas.
  • const and discriminator are not shown; x-codeSamples (Redoc's custom samples) and x-tagGroups are ignored.
  • Headings deeper than ### are not listed in the navigation.
  • OAuth2 authorizationCode and implicit flows take a token obtained elsewhere; there is no redirect flow.