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.

FileKindSize
SKILL.mdskill md4.2 KB
references/api.mdmarkdown1.2 KB
references/frameworks.mdmarkdown5.2 KB
references/migration.mdmarkdown467 B

references/frameworks.md

View on GitHub
# Framework recipes: API reference

Each recipe assumes the shared `openapi` instance from SKILL.md (`lib/openapi.ts`). Change the import paths to match the project's alias. MDX docs routes are in the `ariadocs-mdx` skill.

## Next.js App Router

API reference, one page per endpoint:

```tsx title="app/reference/layout.tsx"
import { OpenAPI } from "@ariadocs/components";
import { openapi } from "@/lib/openapi";

export default async function Layout({ children }: { children: React.ReactNode }) {
  const api = await openapi.parse();
  return (
    <OpenAPI.Root api={api} operationBaseHref="/reference">
      {children}
    </OpenAPI.Root>
  );
}
```

```tsx title="app/reference/[operation]/page.tsx"
import { notFound } from "next/navigation";
import { OpenAPI } from "@ariadocs/components";
import { openapi } from "@/lib/openapi";

export default async function Page({ params }: { params: Promise<{ operation: string }> }) {
  const { operation } = await params;
  if (!(await openapi.getOperation(operation))) notFound();
  return <OpenAPI.Operation id={operation} headingLevel={1} />;
}

export async function generateStaticParams() {
  const paths = await openapi.getPagePaths();
  return paths.map((path) => ({ operation: path.slice(1) }));
}
```

```tsx title="app/reference/page.tsx"
import { OpenAPI } from "@ariadocs/components";

export default function Page() {
  return <OpenAPI.Info />;
}
```

For a small API on a single page, use `<OpenAPI.Root api={api}><OpenAPI.Docs /></OpenAPI.Root>`.

Inside a `Docs.Layout` (shared with MDX docs), the endpoint page returns `<Docs.Content>` only, without `Docs.Aside`, and the layout drops the TOC column. See the `ariadocs-components` skill.

## Next.js Pages Router

```tsx title="pages/reference/[operation].tsx"
import type { GetStaticPaths, GetStaticProps } from "next";
import type { APISpec } from "@ariadocs/openapi";
import { OpenAPI } from "@ariadocs/components";
import { openapi } from "@/lib/openapi";

type Props = { api: APISpec; operation: string };

export default function Page({ api, operation }: Props) {
  return (
    <OpenAPI.Root api={api} operationBaseHref="/reference">
      <OpenAPI.Operation id={operation} headingLevel={1} />
    </OpenAPI.Root>
  );
}

export const getStaticProps: GetStaticProps<Props> = async ({ params }) => {
  const api = await openapi.parse();
  // props must be plain JSON: drop undefined fields
  return { props: { api: JSON.parse(JSON.stringify(api)), operation: String(params?.operation) } };
};

export const getStaticPaths: GetStaticPaths = async () => {
  const paths = await openapi.getPagePaths();
  return { paths: paths.map((path) => ({ params: { operation: path.slice(1) } })), fallback: false };
};
```

For large specs, pass only the operation (`await openapi.getOperation(id)`) and render `<OpenAPI.Operation operation={operation} />` without `Root`. Authorization details need the full spec, so they are not shown.

The global CSS import (`@ariadocs/components/styles.css`) goes in `pages/_app.tsx`.

## React Router v7 and v8 (framework mode)

```ts title="app/routes.ts"
import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [index("routes/home.tsx"), route("reference/:operation", "routes/reference.tsx")] satisfies RouteConfig;
```

```tsx title="app/routes/reference.tsx"
import { useLoaderData } from "react-router";
import { OpenAPI } from "@ariadocs/components";
import type { Route } from "./+types/reference";
import { openapi } from "../openapi";

export async function loader({ params }: Route.LoaderArgs) {
  return { api: await openapi.parse(), operation: params.operation };
}

export default function ReferencePage() {
  const { api, operation } = useLoaderData<typeof loader>();
  return (
    <OpenAPI.Root api={api} operationBaseHref="/reference">
      <OpenAPI.Operation id={operation} headingLevel={1} />
    </OpenAPI.Root>
  );
}
```

```ts title="react-router.config.ts"
import type { Config } from "@react-router/dev/config";
import { openapi } from "./app/openapi";

export default {
  ssr: true,
  async prerender() {
    const paths = await openapi.getPagePaths();
    return paths.map((path) => `/reference${path}`);
  },
} satisfies Config;
```

The CSS import goes in `app/root.tsx` (or `app/app.css` via `@import`).

## TanStack Start

Loaders also run in the browser during client navigation, so anything that reads files goes through `createServerFn`.

```tsx title="src/routes/reference/$operation.tsx"
import { createFileRoute } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { OpenAPI } from "@ariadocs/components";
import { openapi } from "../../openapi";

const getSpec = createServerFn({ method: "GET" }).handler(() => openapi.parse());

export const Route = createFileRoute("/reference/$operation")({
  loader: () => getSpec(),
  component: ReferencePage,
});

function ReferencePage() {
  const api = Route.useLoaderData();
  const { operation } = Route.useParams();
  return (
    <OpenAPI.Root api={api} operationBaseHref="/reference">
      <OpenAPI.Operation id={operation} headingLevel={1} />
    </OpenAPI.Root>
  );
}
```

`openapi.parse()` caches its result, so the spec is read once per server process. The CSS import goes in `src/routes/__root.tsx`.
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: 322kUpdated 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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall