OpenAPI Embed

OpenApiEmbed turns a remote OpenAPI or Swagger URL into a full API reference inside an MDX page. The fetch, the validation, and the rendering all run on the server, so every endpoint ships as plain HTML that OwnDocs search and search engines can read. Operations render through the same API Blocks, ParamField, and ResponseField components used on hand-written API reference pages. There's no CLI step and no generated file to keep in sync.

Quick Start

One tag with a URL is the whole setup. The embed below reads the live Swagger Petstore document, groups its operations by tag, and keeps the fetch cached for an hour.

<OpenApiEmbed url="https://petstore3.swagger.io/api/v3/openapi.json" />

Adding Options

Two props shape what readers get. revalidate sets the cache window in seconds, and showOverview={false} drops the title, version, servers, Postman button, and summary line so only the operation list remains. Combine them when the surrounding page already introduces the API and the spec changes often.

<OpenApiEmbed
  url="https://api.example.com/openapi.yaml"
  revalidate={300}
  showOverview={false}
/>

Advanced

JSON and YAML both work. The component reads the response content type and falls back to the URL file extension when the server sends none, so a plain .yaml file served as text/plain still parses. Pass revalidate={0} while a spec is still moving and every page render refetches it.

<OpenApiEmbed
  url="https://example.com/specs/internal-api.yaml"
  revalidate={0}
/>

Grouping And Methods

• Operations group by their first tag. Without tags, they group by the first path segment, and a leading version segment such as /v1 falls through to the next one.
• GET, POST, PUT, PATCH, and DELETE render. HEAD, OPTIONS, and TRACE are skipped.
• Sample requests carry a placeholder auth header built from the spec's security scheme, such as Authorization: Bearer <token> or X-API-Key: <api-key>. The component stores no credentials and forwards nothing from the reader's browser.
• Source examples render as published. The upstream document decides what readers see.

Failure Handling

The embed fails closed. When a source can't be loaded, an inline banner names the URL and the cause, and the rest of the page still renders. These are the cases it catches:

• A URL that won't parse, or a protocol other than http and https
• A host that stays silent past the 15-second timeout, or answers non-2xx
• More than five redirect hops
• A body that isn't valid JSON or YAML
• A document that isn't OpenAPI 3.0, 3.1, 3.2, or Swagger 2.0
• A document larger than 10 MB

Postman Export

The overview block renders a "Postman collection" download button. OwnDocs converts the source spec to a Postman v2.1 collection on the server during render and memoizes the result per resolved spec URL, so a repeat visit skips the converter. The click streams the JSON as a Blob URL. That file imports into Postman or feeds Newman for command-line testing. You'll find the button at the top of the Petstore embed above.

Options