Skip to main content

Getting Started

Render interactive OpenAPI, Swagger, and AsyncAPI documentation in your React app in under two minutes.

Packages​

PackageSpecsInstall
@apiboost/omnispecOpenAPI 2.0–3.1, AsyncAPI 2.x–3.xnpm install @apiboost/omnispec
@apiboost/omnispec-pro+ GraphQL, SOAP/WSDL, gRPC, theme overrides, interactive OAuthnpm install @apiboost/omnispec @apiboost/omnispec-pro

Peer dependencies: React 18 or 19 (react, react-dom). Everything else, including @emotion/css for styling, is bundled as a normal dependency — no separate install needed. (Pro additionally requires @apiboost/omnispec as a peer, shown above.)

Quick Start​

import { OmniSpecRenderer } from '@apiboost/omnispec'

function OmniSpec() {
  return (
    <OmniSpecRenderer
      spec="https://petstore3.swagger.io/api/v3/openapi.json"
    />
  )
}

That's it. The component fetches the spec, auto-detects the type, and renders full documentation with sidebar navigation, schema viewers, code samples, and a Try-It panel.

New to how the pieces fit together? Read Concepts for the mental model.

Adding Pro​

Pro

GraphQL, SOAP/WSDL, and gRPC renderers, plus full theme-token white-labeling, require Apiboost OmniSpec Pro. In the free core, OpenAPI and AsyncAPI specs render fully; other spec types display a styled upgrade prompt.

Pro is activated by importing the pre-wired OmniSpecRenderer from @apiboost/omnispec-pro — it needs no provider or extra configuration:

import { OmniSpecRenderer } from '@apiboost/omnispec-pro'

function OmniSpec() {
  return <OmniSpecRenderer spec="/schema.graphql" />
}

Alternatively, keep importing from @apiboost/omnispec and pass the Pro capability object through the pro prop. (The deprecated <ProProvider> wrapper still works but should not be used in new code.) See Free vs Pro.

Choose your integration​

How you embed the renderer depends on your stack:

  • React app → import the <OmniSpecRenderer> React component (shown above).
  • Docs site (Docusaurus, etc.) → follow the Docusaurus guide.
  • Non-React app (Vue, Angular, Svelte, vanilla HTML) → use the Web Component.

See Integrations for the full decision guide and per-framework recipes.

Server-side rendering​

OmniSpec is a client-rendered component — it parses the spec and renders the documentation in the browser after mount. It does not crash under renderToString or static builds, but the server output is only a themed shell: the API documentation renders (and hydrates) on the client, so there is no server-rendered content for SEO or no-JS clients. Mount it inside a client-only boundary in SSR/SSG frameworks:

  • Next.js: add 'use client', or use dynamic(() => import('@apiboost/omnispec').then((m) => m.OmniSpecRenderer), { ssr: false }).
  • Docusaurus and other static-site generators: wrap it in a client-only boundary (e.g. Docusaurus's <BrowserOnly>) to avoid a hydration mismatch. See the Docusaurus guide.

Passing Specs​

Specs can be provided as a URL, raw content string, or pre-parsed object:

// URL — fetched automatically
<OmniSpecRenderer spec="https://api.example.com/openapi.json" />

// Raw JSON/YAML string
<OmniSpecRenderer spec={yamlString} />

// Pre-parsed JavaScript object
<OmniSpecRenderer spec={parsedSpecObject} />

// Force a specific spec type (skip auto-detection)
import { SpecType } from '@apiboost/omnispec'
<OmniSpecRenderer spec={specUrl} specType={SpecType.ASYNCAPI_3} />

OpenAPI and AsyncAPI accept JSON or YAML. GraphQL accepts SDL strings or introspection results. SOAP accepts WSDL XML. gRPC accepts .proto file content.

GraphQL introspection exports: getIntrospectionQuery()'s defaults omit the schema description, @specifiedBy URLs on custom scalars, and argument/input-field deprecation. To make an introspection export render identically to its SDL, generate it with the full-fidelity options:

import { getIntrospectionQuery } from 'graphql'

getIntrospectionQuery({
  specifiedByUrl: true,
  schemaDescription: true,
  inputValueDeprecation: true,
  directiveIsRepeatable: true,
})

Supported Specifications​

ComponentSpec TypeVersionsPackage
<OmniSpecRenderer>Auto-detectAll below@apiboost/omnispec
<OpenApiSpec>OpenAPI / Swagger2.0, 3.0.x, 3.1@apiboost/omnispec
<AsyncApiSpec>AsyncAPI2.x — 3.x@apiboost/omnispec
<GraphqlSpec>GraphQL SDLAny@apiboost/omnispec-pro
<SoapSpec>WSDL / SOAP1.1@apiboost/omnispec-pro
<GrpcSpec>Protocol Buffersproto2, proto3@apiboost/omnispec-pro

<OmniSpecRenderer> auto-detects the spec type and lazy-loads only the renderer needed. When you render with @apiboost/omnispec-pro (or pass the pro prop), all spec types render automatically.

Next steps​