tazo90/next-openapi-gen

README

next-openapi-gen

Generate OpenAPI 3.0, 3.1, and 3.2 from the routes and schemas you already have.

next-openapi-gen scans Next.js, TanStack Router, React Router, Remix, SvelteKit, Nuxt, Astro, Hono, and Express route handlers, reads JSDoc metadata, and generates an OpenAPI spec plus an optional docs UI. It is built for real codebases that use Zod, TypeScript, drizzle-zod, or reusable OpenAPI fragments, including mixed-schema migrations.

Quick start • Config reference • Docs index • Example apps • Validation and coverage

Why teams use it

Keep OpenAPI close to your handlers instead of maintaining a separate manual spec.
Reuse existing zod, typescript, drizzle-zod, and YAML/JSON OpenAPI fragments in one pipeline.
Target 3.0, 3.1, or 3.2 from the same route metadata with version-aware finalization.
Ship interactive docs quickly with built-in UI scaffolding for Scalar, Swagger, Redoc, Stoplight Elements, or RapiDoc.
Fall back on checker-assisted App Router response inference when explicit @response tags are missing.
Keep richer Zod 4 and TypeScript output in modern targets with selective runtime-assisted Zod export and checker fallback for advanced type constructs.

Quick start

Requirements

Node.js >=24
TypeScript >=5.9 <8 for TypeScript schemas and checker-assisted response inference. The generator prefers your project-installed TypeScript, uses TypeScript 7's native checker API when available, and falls back to its bundled TypeScript 6 compatibility compiler when needed.
A supported app framework:
- Next.js using App Router or Pages Router
- TanStack Router
- React Router
- Remix
- SvelteKit
- Nuxt
- Astro
- Hono
- Express

Install

pnpm add -D next-openapi-gen

npm install --save-dev next-openapi-gen

yarn add --dev next-openapi-gen

Initialize and generate

# Next.js is the default framework
pnpm exec openapi-gen init

# Or choose another supported framework
pnpm exec openapi-gen init --framework tanstack
pnpm exec openapi-gen init --framework react-router

# Scans your routes and writes the spec once
pnpm exec openapi-gen generate

# Keeps the spec fresh during local development
pnpm exec openapi-gen generate --watch

Tip

Use --ui none during init if you only want the generated OpenAPI file.

The package name is still next-openapi-gen during the transition. Config discovery also accepts the new openapi-gen.config.ts and openapi-gen.config.json aliases, while next-openapi.config.* and next.openapi.json continue to work with deprecation warnings. The legacy next-openapi-gen binary still works too, but openapi-gen is the preferred CLI name going forward.

Need the full setup flow, config walkthrough, or production notes? See docs/getting-started.md.

Note

TypeScript 7 ships a faster native CLI and language server, but its stable programmatic API is still in transition. Projects can use TypeScript 7 for tsc; next-openapi-gen will use the native checker API when it is exposed by the installed package, otherwise it falls back to the bundled TypeScript 6 API. TypeScript 5.9 remains the minimum supported compiler for consumers.

What you get

openapi-gen.config.ts in your project root
public/openapi.json by default
/api-docs with your selected UI provider by default

Framework support

Framework	Setup path	Notes
Next.js	`pnpm exec openapi-gen init`	Supports App Router and Pages Router
TanStack Router	`pnpm exec openapi-gen init --framework tanstack`	Uses the public `next-openapi-gen/vite` plugin surface
React Router	`pnpm exec openapi-gen init --framework react-router`	Uses the public `next-openapi-gen/react-router` plugin surface
Remix	`pnpm exec openapi-gen init --framework remix`	Vite plugin via `next-openapi-gen/remix`
SvelteKit	`pnpm exec openapi-gen init --framework sveltekit`	Vite plugin via `next-openapi-gen/sveltekit`
Nuxt	`pnpm exec openapi-gen init --framework nuxt`	Nitro module via `next-openapi-gen/nuxt`
Astro	`pnpm exec openapi-gen init --framework astro`	Astro integration via `next-openapi-gen/astro`
Hono	`pnpm exec openapi-gen init --framework hono`	Vite plugin via `next-openapi-gen/hono`
Express	`pnpm exec openapi-gen init --framework express`	CLI or `generateExpressOpenApi()` helper

Minimal example

import { NextRequest } from "next/server";
import { z } from "zod";

export const ProductParams = z.object({
  id: z.string().describe("Product ID"),
});

export const ProductResponse = z.object({
  id: z.string(),
  name: z.string(),
  price: z.number().positive(),
});

/**
 * Get product information
 * @description Fetch a product by ID
 * @path ProductParams
 * @response ProductResponse
 * @openapi
 */
export async function GET(request: NextRequest, { params }: { params: { id: string } }) {
  return Response.json({ id: params.id, name: "Keyboard", price: 99 });
}

Why `next-openapi-gen` is different

Capability	Why it matters
Framework-aware route scanning	Covers Next.js, TanStack Router, React Router, Remix, SvelteKit, Nuxt, Astro, Hono, and Express.
Mixed schema sources	Combine `zod`, `typescript`, `schemaFiles`, and drizzle-zod-backed schemas during gradual migrations.
OpenAPI `3.0` / `3.1` / `3.2` targets	Keep one authoring flow while emitting version-aware output for newer spec features.
Response inference	Infer typed App Router responses when `@response` is omitted, while still letting explicit tags win.
Docs UI scaffolding	Generate a docs page fast instead of stopping at a JSON file.

Common workflows

Start with Zod or TypeScript

Use one schema system if your app is already consistent:

schemaType: "zod",
schemaDir: "src/schemas",

Migrate gradually with mixed schema sources

Use multiple schema types in the same project when you are moving from TypeScript to Zod or merging generated and hand-authored schemas:

schemaType: ["zod", "typescript"],
schemaDir: "./src/schemas",
schemaFiles: ["./schemas/external-api.yaml"],

Resolution priority is:

schemaFiles
zod
typescript

See apps/next-app-mixed-schemas for a full working example. For more adoption patterns, see docs/workflows-and-integrations.md.

When you target modern OpenAPI output, the Zod path can also split request and response component refs when a supported Zod 4 schema emits different input and output JSON Schema shapes, while the TypeScript path can use selective checker fallback for mapped, conditional, template-literal, and import-based named types.

Add OpenAPI metadata directly in Zod schemas

Use .describe() for a quick description, or Zod v4's .meta() to attach description, examples, example, deprecated, title, and custom x-* extensions without any JSDoc:

// .describe() → description field
z.string().describe("ISO 639-1 language code");
// → { type: "string", description: "ISO 639-1 language code" }

// .meta() → description + examples (and any other OpenAPI key)
z.number()
  .int()
  .positive()
  .meta({
    description: "PIM ID of the slider",
    examples: [42, 1337],
  });
// → { type: "integer", exclusiveMinimum: 0, description: "PIM ID of the slider", examples: [42, 1337] }

Both work inside z.object({...}) properties, in drizzle-zod override callbacks, and at the top level of named schemas. See docs/zod4-support-matrix.md for the full supported metadata surface.

Decouple component names from source identifiers

Use .meta({ id }) for Zod schemas or /** @id */ for TypeScript types to set the OpenAPI component name independently of the export name — useful when enforcing PascalCase naming or migrating from another generator without renaming existing exports:

// Zod: use .meta({ id }) to decouple the component name from the variable name
export const audioSchema = z.object({ ... }).meta({ id: "Audio" });
// → components.schemas.Audio (not: audioSchema)

// TypeScript: use /** @id */ at the declaration level
/** @id Audio */
export interface AudioInterface { ... }
// → components.schemas.Audio (not: AudioInterface)

Existing @requestBody audioSchema or @response audioSchema references in route handlers continue to work — the generator resolves them transparently to the override name. See docs/jsdoc-reference.md#component-naming for details.

Generate docs from Drizzle schemas

next-openapi-gen works well with drizzle-zod, so your database schema, validation, and API docs can share the same source of truth.

import { createInsertSchema, createSelectSchema } from "drizzle-zod";
import { posts } from "@/db/schema";

export const CreatePostSchema = createInsertSchema(posts, {
  title: (schema) => schema.title.min(5).max(255),
  content: (schema) => schema.content.min(10),
});

export const PostResponseSchema = createSelectSchema(posts);

See apps/next-app-drizzle-zod for the full CRUD example.

Rely on inference when you want less annotation

If you omit @response, App Router handlers can infer responses from typed NextResponse.json(...) and Response.json(...) returns.

import { NextResponse } from "next/server";

type SearchResponse = {
  total: number;
};

/**
 * Search events
 * @responseDescription Search result
 * @openapi
 */
export async function POST(): Promise<NextResponse<SearchResponse>> {
  return NextResponse.json({ total: 3 });
}

Explicit @response tags still take precedence when you want stable schema names or exact response codes.

Configuration

init creates an openapi-gen.config.ts file like this:

import { defineConfig } from "next-openapi-gen";

export default defineConfig({
  openapi: "3.0.0",
  info: {
    title: "Next.js API",
    version: "1.0.0",
    description: "API generated by next-openapi-gen",
  },
  apiDir: "src/app/api",
  routerType: "app",
  schemaDir: "src/schemas",
  schemaType: "zod",
  schemaFiles: [],
  outputFile: "openapi.json",
  outputDir: "./public",
  docsUrl: "api-docs",
  includeOpenApiRoutes: false,
  ignoreRoutes: [],
  debug: false,
});

Version guidance:

Use 3.0.0 when you want the broadest downstream tooling compatibility.
Use 3.1.0 when you want JSON Schema 2020-12-aligned output such as jsonSchemaDialect.
Use 3.2.0 when you want first-class querystring, enhanced tag metadata, sequential media, and richer example objects.

Important options

Option	Purpose
`openapi`	Target `3.0.0`, `3.1.0`, `3.2.0`, or experimental `3.3-preview` output
`apiDir`	Route directory to scan
`routerType`	`"app"` or `"pages"`
`schemaDir`	Directory or directories to search for schemas/types
`schemaType`	`"zod"`, `"typescript"`, or both
`schemaFiles`	YAML/JSON OpenAPI fragments to merge into the generated document
`includeOpenApiRoutes`	Only include handlers tagged with `@openapi`
`ignoreRoutes`	Exclude routes with wildcard support
`excludeSchemas`	Exclude internal schemas from `components/schemas` by name or glob (e.g. `["*Params"]`)
`defaultResponseSet` / `responseSets`	Reusable error-response groups
`errorConfig`	Shared error schema templates
`authPresets`	Override or extend the `@auth` keyword → scheme-name mapping
`diagnostics.failOn`	CI gate: `"never"` (default), `"warning"`, or `"error"`

During generation, the CLI prints diagnostics grouped by severity (error, warning, info) and also writes them to .openapi-gen/manifest.json in non-production runs. Common codes include missing-query-params-type, multipart-missing-body-schema, schema-not-found, schema-dir-empty, path-param-schema-conflict, unknown-zod-helper, unknown-zod-method, unresolved-zod-argument, type-resolution-fallback, inferred-path-params, inferred-query-params, and inferred-body.

For a fuller setup guide, Pages Router notes, response sets, and route exclusion patterns, see docs/getting-started.md. For every public config field, including client SDK generation, hooks, docs artifacts, cache semantics, Overlay, and Arazzo, see the complete configuration reference.

JSDoc tags you will use most

Tag	Purpose
`@path` / `@pathParams`	Path parameter schema or type
`@query` / `@params` / `@queryParams`	Query parameter schema or type
`@header` / `@cookie`	Header / cookie parameter schema or type
`@requestBody` / `@body`	Request body schema or type; append `required` to set `requestBody.required`
`@response`	Response schema, code, and optional description
`@responseDescription`	Response description without redefining the schema
`@responseHeader`	Add a response header to a given status code
`@link`	Add an OpenAPI link to a response
`@auth` / `@security`	Security requirement(s); built-in presets: `bearer`, `basic`, `apikey` — configurable via `authPresets`
`@servers`	Operation-level servers
`@externalDocs`	Operation-level external documentation
`@callback`	OpenAPI operation callback
`@webhook`	Mark the handler as a webhook (`3.1`+ `webhooks` section)
`@requestContentType` / `@contentType`	Request content type such as `multipart/form-data`
`@examples`	Request, response, querystring, query, header, and cookie examples
`@openapi`	Explicit inclusion marker when `includeOpenApiRoutes` is enabled
`@openapi-override`	Deep-merge extra OpenAPI fields onto the operation
`@ignore`	Exclude a route from generation
`@internal`	Exclude a schema/type declaration from `components/schemas`
`@method`	Override or declare the HTTP method; `QUERY` emits the OpenAPI 3.2 Path Item `query` field

For the complete tag guide and usage recipes, see docs/jsdoc-reference.md.

OpenAPI 3.2-specific tags such as @querystring, @tagSummary, @tagKind, @itemSchema, and sequential media annotations are documented in the same guide and shown in apps/next-app-zod.

Compatibility

Area	Support
Frameworks	Next.js, TanStack Router, React Router, Remix, SvelteKit, Nuxt, Astro, Hono, Express
Next.js routers	App Router and Pages Router
OpenAPI targets	`3.0`, `3.1`, `3.2`, experimental `3.3-preview`
Schema sources	`zod`, `typescript`, drizzle-zod output, YAML/JSON fragments
Docs UIs	Scalar, Swagger, Redoc, Stoplight Elements, RapiDoc

For Pages Router projects, set routerType to "pages" and annotate handlers with @method. See apps/next-pages-router.

For the supported Zod 4 surface and known gaps, see docs/zod4-support-matrix.md.

Framework integrations

Use the integration that matches your framework:

next-openapi-gen/next: Next.js adapter helpers such as createNextOpenApiAdapter
next-openapi-gen/vite: Vite plugin surface used by the TanStack example app
next-openapi-gen/react-router: React Router plugin surface
next-openapi-gen/remix: Remix Vite plugin
next-openapi-gen/sveltekit: SvelteKit Vite plugin
next-openapi-gen/nuxt: Nuxt/Nitro module
next-openapi-gen/astro: Astro integration
next-openapi-gen/hono: Hono Vite plugin
next-openapi-gen/express: Express generate helper

The main package export also exposes generateProject, watchProject, and config helpers when you want to script generation directly.

Example apps

Use the checked-in examples to evaluate the tool in realistic setups:

apps/next-app-zod: Zod-first App Router example
apps/next-app-next-config: typed config example targeting OpenAPI 3.1
apps/next-app-typescript: TypeScript-first example
apps/next-app-mixed-schemas: mixed schema migration example
apps/next-app-drizzle-zod: Drizzle + drizzle-zod CRUD example
apps/next-app-sandbox: edge-case route and exclusion playground
apps/next-app-ts-config: typed config loading and clientSdk golden path
apps/next-app-adapter: Next adapter integration smoke example
apps/next-pages-router: legacy Pages Router support
apps/tanstack-app: TanStack Router framework parity example
apps/react-router-app: React Router framework parity example
apps/remix-app: Remix file-route parity example
apps/sveltekit-app: SvelteKit +server parity example
apps/nuxt-app: Nuxt/Nitro filename-method parity example
apps/astro-app: Astro endpoint parity example
apps/hono-app: Hono call-expression parity example
apps/express-app: Express call-expression parity example
apps/next-app-scalar, apps/next-app-swagger: docs UI variants

Run an example

pnpm install
cd apps/next-app-zod
pnpm exec openapi-gen generate
pnpm dev

Then open http://localhost:3000/api-docs.

Validation and coverage

This repo is not just a demo. The CI pipeline covers:

formatting and linting
workspace builds
unit tests
integration tests
coverage reporting
Playwright E2E runs across an app matrix

For the detailed version matrix and validation notes, see:

The checked-in examples intentionally span different goals: most apps stay on 3.0 as the conservative default, apps/next-app-next-config demonstrates a typed 3.1 config, and apps/next-app-zod showcases richer 3.2 route and document features.

Available UI providers

Scalar	Swagger	Redoc	Stoplight Elements	RapiDoc

Advanced docs

Use these deeper references when you need more than the quick start:

docs/README.md: docs index
docs/getting-started.md: setup, config, framework defaults, watch mode, and production notes
docs/configuration-reference.md: complete public config surface, client SDK workflow, hooks, docs, and cache side effects
docs/jsdoc-reference.md: full route tag reference and examples
docs/workflows-and-integrations.md: framework integrations, mixed schemas, drizzle-zod, and downstream workflows
docs/faq.md: troubleshooting and common questions
docs/openapi-version-coverage.md: version-specific behavior, validation strategy, and generated vs preserved fields
docs/zod4-support-matrix.md: tested Zod 4 coverage and known boundaries
docs/example-app-coverage-plan.md: example app roles, coverage goals, and expansion roadmap
apps: complete runnable examples

CLI

pnpm exec openapi-gen init
pnpm exec openapi-gen generate
pnpm exec openapi-gen generate --watch

`init` options

Option	Choices	Default
`--framework`	`next`, `tanstack`, `react-router`	`next`
`--ui`	`scalar`, `swagger`, `redoc`, `stoplight`, `rapidoc`, `none`	`scalar`
`--schema`	`zod`, `typescript`	`zod`
`--docs-url`	any string	`api-docs`
`--output`	any path	`openapi-gen.config.ts`

`generate` options

Option	Purpose
`--config`	Use a specific config file
`--template`	Merge a specific OpenAPI template or fragment
`--watch`	Regenerate when routes or schema files change
`--fail-on`	Exit with an error when diagnostics reach `error`, `warning`, or `never`

Generated diagnostics are printed after each run and recorded in .openapi-gen/manifest.json (development only) for automation and CI review.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, commit conventions, and workflow details.

Changelog

See CHANGELOG.md for release history and recent changes.

License

MIT