OpenAPI Embed

This page shows the OpenApiEmbed component, an MDX tag that renders a full API reference inline from a remote OpenAPI or Swagger URL. At render time, OwnDocs fetches the spec, checks it against OpenAPI 3.0/3.1/3.2 or Swagger 2.0, redacts credential-like values, and renders each operation with the standard ApiBlock, ParamField, and ResponseField components. There's no CLI, no generated files, and no manual conversion step. Use the page as a working reference for the official Swagger Petstore, or as a template for your own API docs.

Live Example: Swagger Petstore

The official Swagger Petstore is the OpenAPI 3.0 reference document kept by the OpenAPI Initiative. The embed below fetches the live JSON spec on the server, parses it, groups operations by tag, and renders each endpoint with the same components used elsewhere on this site.

Usage

To embed a publicly reachable JSON or YAML OpenAPI document, add one tag to your MDX page. The component fetches, validates, and renders it.

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

Custom Cache Window

By default, the fetched specification is cached for one hour through the Next.js fetch cache. Override that window by passing revalidate in seconds. Set to 0 to refetch on every request.

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

Hiding the Overview

The component renders an overview block above the operation list with the API title, version, description, server URLs, and source summary. Hide it for a smaller embed when the page around it already gives context.

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

Embedding a YAML Source

JSON and YAML both work. The component negotiates content types and falls back to the URL file extension when the server omits one.

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

Postman Collection Export

Every embed renders a "Postman collection" download button inside the overview block. OwnDocs converts the source spec to a Postman v2.1 collection on the server during rendering, then streams it as a Blob URL when the reader clicks the button. The conversion is memoized per resolved spec URL, so repeat visits don't re-run the converter. The button sits at the top of the Swagger Petstore embed above. The JSON file it produces imports into Postman or feeds Newman for command-line testing.

Supported Props

The OpenApiEmbed component accepts the following props:

• url — string (required)
  • HTTP(S) URL to a JSON or YAML OpenAPI 3.0/3.1/3.2 or Swagger 2.0 document
• revalidate — number
  • Seconds to cache the fetched spec through the Next.js fetch cache; defaults to 3600. Set to 0 to refetch every render.
• showOverview — boolean
  • Shows the API title, version, description, servers, and source summary above the operation list; defaults to true.

Behavior

The embed runs on the server during page render, so the HTML is pre-rendered, indexed by OwnDocs search, and visible to search engines without extra configuration.

• Operations are grouped by tag. When a source has no tags, operations are grouped by the first non-version segment of each path.
• The component renders the HTTP methods ApiBlock supports (GET, POST, PUT, PATCH, DELETE) and skips the rest.
• Source examples render exactly as published. The component doesn't modify or filter spec content. The upstream OpenAPI document decides what readers see.
• The component uses the same component map as the catch-all route, so ApiBlock interactivity, copy buttons, and theme variants apply.

Failures

The embed fails closed and never crashes the page around it. When something goes wrong, an inline error banner replaces the API reference and names the cause. The rest of the page still renders.

Common failure scenarios include:

• Invalid URL syntax or non-http(s) protocols
• Unreachable hosts or non-2xx HTTP responses
• Redirect chains that exceed the safety limit
• Source documents that are not valid JSON or YAML
• Source documents that are not OpenAPI 3.0/3.1/3.2 or Swagger 2.0
• Source documents larger than 10 MB

Security

The fetcher enforces a small set of guardrails before parsing any source content:

• Only http:// and https:// URLs are accepted; the protocol is re-checked on every redirect hop.
• A request timeout and a redirect limit stop slow or looping sources from blocking page rendering.
• Source documents larger than 10 MB are rejected.
• Source documents that fail JSON or YAML parsing are rejected before rendering.
• The component stores no credentials and doesn't forward request headers from the visitor's browser.

See also

• OpenAPI Specification
• Swagger Petstore
• OpenAPI Initiative examples