nisabmohd/aria-docs / skills/ariadocs-openapi
ariadocs-openapi
VerifiedBuild an API reference from an OpenAPI 3.0/3.1/3.2 spec with @ariadocs/openapi — parse and validate a spec from a file, URL or object, list operations, tags and schemas, build sidebar navigation and per-endpoint static paths, generate code samples, search, and handle untrusted specs. Use when the user wants an API reference, endpoint pages, a spec-driven sidebar, request code samples, or to read an OpenAPI spec in React. Covers Next.js (App and Pages Router), React Router (v7 and v8) and TanStack Start. For rendering and customizing the reference UI use the `ariadocs-components` skill.
@ariadocs/openapi
Parses an OpenAPI spec into one typed, plain-JSON model (APISpec): operations, tags and schemas with $refs resolved. The model can be passed through loaders and props. @ariadocs/components renders it with the OpenAPI.* components.
Related skills: ariadocs-components covers the OpenAPI.* parts and the page shell. ariadocs-mdx adds MDX guides next to the reference.
Workflow
- Inspect the project: framework and router, package manager, path alias, and where the spec lives (file in the repo, URL, or generated).
- Install
@ariadocs/openapi, plus@ariadocs/componentsfor the UI (then follow theariadocs-componentsskill for styles). - Create one shared instance in
lib/openapi.ts(below). - Add routes: copy the matching recipe from references/frameworks.md. Choose one page per endpoint (
/reference/[operation]) or the whole API on one page. - Verify: type check and build, open the reference route and one endpoint page.
Shared instance
import { createOpenAPI } from "@ariadocs/openapi";
// source: file path, URL, JSON/YAML string or spec object
export const openapi = createOpenAPI({ source: "./openapi.yaml" });
openapi methods: parse() (cached), getNavigation(options?), getPagePaths(), getOperation(id), getSchema(name), search(query), reload().
Rendering
const api = await openapi.parse();
// Whole API on one page
<OpenAPI.Root api={api}><OpenAPI.Docs /></OpenAPI.Root>
// One page per endpoint
<OpenAPI.Root api={api} operationBaseHref="/reference">
<OpenAPI.Operation id={operation} headingLevel={1} />
</OpenAPI.Root>
The OpenAPI.* components are Client Components that take plain data, so Server Components can render them. To pick parts, reorder or add your own, see the ariadocs-components skill.
Full export list: references/api.md.
Rules and gotchas
- Endpoint pages:
openapi.getPagePaths()returns["/emails-send", ...], so strip the leading/for an[operation]param. Operation ids come fromoperationId, or are derived from method and path. - Sidebar links:
openapi.getNavigation({ getOperationHref: (op) => \/reference/${op.id}` })returnsNavItem[](one group per tag, with method badges) forDocs.Nav. It has the same shape asdocs.getNavigation()from@ariadocs/mdx, so they can be merged into one sidebar. Or use<OpenAPI.Sidebar />inside aRootwithoperationBaseHref`. operationBaseHrefis a string, not a callback, soOpenAPI.Rootworks from Server Components.- Next.js Pages Router props must be JSON. Pass
JSON.parse(JSON.stringify(api)). For large specs pass only the operation and render<OpenAPI.Operation operation={operation} />withoutRoot. - TanStack Start loaders also run in the browser, so
openapi.parse()must go throughcreateServerFn. - Untrusted specs: for user-supplied specs, use
parseOpenAPI({ source, allowFiles: false, allowRemote: false }). UseallowRemote: falsefor trusted local files too, so$refs can't fetch. - Errors: parsing throws
OpenAPIErrorfor invalid specs. Let it fail the build. Swagger 2.0 is rejected: convert it to OpenAPI 3 first (for example withswagger2openapi). - Code samples:
createRequestSample(operation)pluscreateCodeSample(sample, language)forcurl,javascript,python,go,rust,java,kotlin,csharp.OpenAPI.Operation.RequestExampleuses them. - Migrating from pre-1.0 APIs: see references/migration.md.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |