Skip to content

nisabmohd/aria-docs / skills/ariadocs-openapi

ariadocs-openapi

Verified

Build 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

  1. Inspect the project: framework and router, package manager, path alias, and where the spec lives (file in the repo, URL, or generated).
  2. Install @ariadocs/openapi, plus @ariadocs/components for the UI (then follow the ariadocs-components skill for styles).
  3. Create one shared instance in lib/openapi.ts (below).
  4. Add routes: copy the matching recipe from references/frameworks.md. Choose one page per endpoint (/reference/[operation]) or the whole API on one page.
  5. 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 from operationId, 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 as docs.getNavigation()from@ariadocs/mdx, so they can be merged into one sidebar. Or use <OpenAPI.Sidebar />inside aRootwithoperationBaseHref`.
  • operationBaseHref is a string, not a callback, so OpenAPI.Root works 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} /> without Root.
  • TanStack Start loaders also run in the browser, so openapi.parse() must go through createServerFn.
  • Untrusted specs: for user-supplied specs, use parseOpenAPI({ source, allowFiles: false, allowRemote: false }). Use allowRemote: false for trusted local files too, so $refs can't fetch.
  • Errors: parsing throws OpenAPIError for invalid specs. Let it fail the build. Swagger 2.0 is rejected: convert it to OpenAPI 3 first (for example with swagger2openapi).
  • Code samples: createRequestSample(operation) plus createCodeSample(sample, language) for curl, javascript, python, go, rust, java, kotlin, csharp. OpenAPI.Operation.RequestExample uses them.
  • Migrating from pre-1.0 APIs: see references/migration.md.
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: 319kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall