API references people can actually try
oaspect turns your OpenAPI document into a fast three-column reference: live requests, code in 30 clients, schemas you can read, and docs in your users' language.
<script src="https://cdn.jsdelivr.net/npm/oaspect"
data-spec-url="/openapi.yaml"></script>
import { ApiReference } from "@oaspect/react";
import "@oaspect/react/styles.css";
<ApiReference specUrl="/openapi.yaml" />
# one self-contained, prerendered HTML file
npx oaspect build openapi.yaml -o docs.html
# live preview with a "Try it" proxy
npx oaspect serve openapi.yaml
/beans?origin=ET2008 ms
Send real requests without leaving the docs
Every operation opens a request editor with its parameters, body and auth filled in from the spec.
- CORS-free proxy when your API does not send CORS headers, with a host allowlist.
- File uploads for multipart/form-data, from the editor and in every code sample.
- API key, Basic, Bearer and OAuth2, including token requests for client credentials.
- Write requests ask first, so examples never overwrite real data by accident.
Request bodies you can actually read
$ref, allOf, oneOf and anyOf become a tree you expand field by field, with types, constraints, enums and examples beside each one.
- oneOf variants as tabs, discriminators and titles respected.
- Examples generated from schemas when the spec has none.
- GFM Markdown in descriptions: tables, lists, code blocks; raw HTML never rendered.
Docs in your users' language, right to left included
The interface ships in English, Turkish and Arabic, and takes your own translations. Your spec can be translated too.
x-i18nfor summaries, tag names and descriptions.:::langblocks for long Markdown, with English as the fallback.- Real RTL: logical layout, code and URLs kept left to right.
Fits your stack, not the other way around
Use the standalone script, a web component, the React component or the CLI. Server helpers cover the parts a static page cannot.
- Works on a phone: the reference collapses to one column with a drawer.
- Light and dark, following the system or your choice.
<oaspect-reference
spec-url="/openapi.yaml"
locale="tr"></oaspect-reference>
<script src="https://cdn.jsdelivr.net/npm/oaspect"></script>
const docs = Oaspect.init("#docs", {
specUrl: "/openapi.yaml",
proxyUrl: "/api/proxy",
logo: { light: "/logo.svg", dark: "/logo-dark.svg" },
});
docs.update({ locale: "ar" });
// app/api/proxy/route.js — "Try it" for APIs without CORS
import { createProxyHandler } from "oaspect/server";
export const POST = createProxyHandler({
allowedHosts: ["api.example.com"],
});
import { readFile } from "node:fs/promises";
import { createSpecHandler } from "oaspect/server";
// the live spec, server-side (no CORS), or the bundled copy
export const GET = createSpecHandler({
url: process.env.SPEC_URL,
fallback: () => readFile("openapi.json", "utf8"),
});
Small, complete, dependable
Prerendered and lazy
The CLI writes static HTML that search engines index and that reads without JavaScript; large documents render sections as you scroll.
Scoped styles
Every rule lives under .oaspect, cascade layers unwrapped: drop it into any page or framework without CSS fights.
WCAG AA
Contrast-checked themes, keyboard focus everywhere, landmarks and a skip link. Tested with axe-core.
Webhooks, callbacks, links
OpenAPI 3.1 webhooks, callbacks under their operations, response links and server variables.
Server helpers
Web-standard Request/Response handlers for the Try proxy and the spec: Next.js, Hono, Bun, Workers or plain Node.
Swagger 2.0, YAML, $ref
Converts Swagger 2.0 on load, reads YAML, and resolves references split across files.
See it with real documents
Each demo is a single prerendered HTML file built by oaspect build.
RoasteryOpenAPI 3.1 showcase: Turkish and Arabic, oneOf, uploads, webhooks
LivenessGuide sections: a WebSocket protocol documented with headings and prose
Developer docsThis site's Markdown docs in the docs viewer: navigation, search, Mermaid
PrintThe Roastery API as a printable book: cover, contents, chapters, APA 7
BookstoreOpenAPI 3.0: schemas, allOf/oneOf, code samples
PetstoreSwagger 2.0 YAML, converted on load; multipart upload
EventsOpenAPI 3.1 webhooks, callbacks, links, server variables
AuthAPI key, Basic and OAuth2 security schemes
Your API deserves docs people use
One script tag and your OpenAPI file. No account, no build, MIT licensed.