OpenAPI Embed

This page demonstrates the OpenApiEmbed component — a drop-in MDX tag that auto-renders an entire API reference inline from a remote OpenAPI or Swagger URL. ClearDocs fetches the specification at render time, validates it against OpenAPI 3.0/3.1/3.2 or Swagger 2.0 compatibility, redacts any credential-like values, and renders every operation using the standard ApiBlock, ParamField, and ResponseField components. There is no CLI, no generated files, and no manual conversion step. Use this page as both a working reference for the official Swagger Petstore and a template for embedding your own API documentation.

Live Example: Swagger Petstore

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

Usage

To embed any publicly reachable JSON or YAML OpenAPI document, drop a single tag into your MDX page. The component handles fetching, validation, and rendering automatically.

<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 more compact embed when the surrounding MDX already provides context.

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

Embedding a YAML Source

JSON and YAML are both supported. The component negotiates content types and falls back to the URL file extension when the server omits a content type.

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

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 specification through the Next.js fetch cache; defaults to 3600. Set to 0 to refetch every render.
• showOverview — boolean
  • Render 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 resulting HTML is pre-rendered, indexed by the ClearDocs search index, 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.
• HTTP methods supported by ApiBlock (GET, POST, PUT, PATCH, DELETE) are rendered. Other methods are skipped.
• Source examples are rendered exactly as published. The component does not modify or filter spec content; the upstream OpenAPI document is treated as authoritative for what readers will see.
• The component uses the same component map as the catch-all route, so ApiBlock interactivity, copy buttons, and theme variants apply automatically.

Failure Handling

The embed fails closed and never crashes the surrounding page. When something goes wrong, an inline error banner is rendered in place of the API reference with a safe message describing the failure cause. The rest of the page continues to render normally.

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 any source content is parsed:

• Only http:// and https:// URLs are accepted; the protocol is re-checked on every redirect hop.
• A request timeout and a redirect limit prevent 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 does not store credentials and does not forward request headers from the visitor's browser.

References

• OpenAPI Specification
• Swagger Petstore
• OpenAPI Initiative examples