Frameworks
Recipes for common stacks. React apps use @oaspect/react; everything else uses the standalone script or the <oaspect-reference> web component.
Plain HTML and static sites
Hugo, Jekyll, Eleventy, a CMS page or a bare HTML file: add the script where the reference should appear.
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/oaspect.js" data-spec-url="/openapi.yaml"></script>The reference fills the width of its container and uses the page's scroll. Give it the whole page (body { margin: 0 }) for the three-column layout. Its header is sticky at the top of the viewport, so it sits best on a page without another sticky header.
Next.js
The component uses state and browser APIs, so render it from a client component. The App Router layout imports the stylesheet once:
// app/layout.js
import "@oaspect/react/styles.css";
export default function RootLayout({ children }) {
return (
<html lang="en">
<body style={{ margin: 0 }}>{children}</body>
</html>
);
}// app/docs/page.js
"use client";
import { ApiReference } from "@oaspect/react";
export default function Docs() {
return <ApiReference specUrl="/openapi" proxyUrl="/api/proxy" />;
}Route handlers can serve the document and relay Try requests (see Server helpers):
// app/openapi/route.js: the live document, or the bundled copy
import { readFile } from "node:fs/promises";
import { join } from "node:path";
import { createSpecHandler } from "oaspect/server";
export const GET = createSpecHandler({
url: process.env.SPEC_URL,
fallback: () => readFile(join(process.cwd(), "public/openapi.json"), "utf8"),
});// app/api/proxy/route.js
import { createProxyHandler } from "oaspect/server";
export const POST = createProxyHandler({ allowedHosts: ["api.example.com"] });A complete app is in examples/nextjs.
Remembering the language
To keep the reader's language between visits (and render it on the server), make the locale controlled and store it in a cookie:
"use client";
import { ApiReference, directionOf } from "@oaspect/react";
import { useState } from "react";
export default function Docs({ initialLocale }) {
const [locale, setLocale] = useState(initialLocale);
return (
<ApiReference
specUrl="/openapi"
locale={locale}
onLocaleChange={(next) => {
document.cookie = `locale=${next}; path=/; max-age=31536000; samesite=lax`;
document.documentElement.lang = next;
document.documentElement.dir = directionOf(next);
setLocale(next);
}}
/>
);
}The server page reads the cookie with cookies() and passes initialLocale.
Vite, Create React App and other React setups
import { ApiReference } from "@oaspect/react";
import "@oaspect/react/styles.css";
export function Docs() {
return <ApiReference specUrl="/openapi.yaml" />;
}Put openapi.yaml in public/. Remix, React Router and TanStack Start work the same way.
Vue, Svelte and other frameworks
Load the standalone script once (in index.html or with a dynamic import) and use <oaspect-reference> in your templates.
Vue: tell the compiler that oaspect-reference is a custom element.
// vite.config.js
import vue from "@vitejs/plugin-vue";
export default {
plugins: [vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === "oaspect-reference" } } })],
};<template>
<oaspect-reference spec-url="/openapi.yaml" :locale="locale" />
</template>Svelte needs no configuration:
<oaspect-reference spec-url="/openapi.yaml" locale={locale}></oaspect-reference>Angular: add CUSTOM_ELEMENTS_SCHEMA to the component's schemas, then use the element in its template.
Attribute changes re-render the reference, so bound values such as locale stay in sync. To pass a document object, set the element's spec property.
Astro
---
// src/pages/docs.astro
---
<html lang="en">
<body style="margin: 0">
<script is:inline src="https://cdn.jsdelivr.net/npm/[email protected]/dist/oaspect.js" data-spec-url="/openapi.yaml"></script>
</body>
</html>To ship a prerendered page instead, generate it with oaspect build into public/.
Node, Express, Hono and Workers
The server helpers take a Web Request and return a Response, so they plug into any server. See Server helpers for Node's http, Express, Hono, Bun, Deno and Cloudflare Workers.