next-oapi

next-oapi

A CLI tool to generate OpenAPI schema from Next.js routes. It analyzes your Next.js API routes and automatically generates comprehensive OpenAPI 3.0 specifications, including schemas for request/response models, enums, and more.

Installation

Install globally via npm:

npm install -g next-oapi

Or using pnpm:

pnpm add -g next-oapi

Or using bun:

bun add -g next-oapi

Usage

After installation, you can use the CLI in your Next.js project directory:

next-oapi --project <path-to-next-project>

For example:

next-oapi --project . --out ./custom-docs

This will generate an openapi.json file in the specified output directory (or the default src/docs/ or docs/ folder).

Options

• --project <path>: Path to the Next.js project directory (required)
• --out <path>: Output directory for the generated openapi.json (optional, defaults to src/docs/ or docs/)
• --help: Show help message

Generated Output

The tool generates a complete OpenAPI 3.0 specification that includes:

• Automatic path detection from your API routes
• Schema inference from TypeScript types and expressions
• Enum generation for union types and literals
• Support for complex response types from NextResponse.json calls
• Cleanup of primitives (no unnecessary wrappers for strings, numbers, booleans)
• Stable schema names with deduplication

Limitations

⚠️ Important: This tool is designed to analyze pure Next.js API routes only. It does not support (and may produce incorrect or incomplete results for):

• Routes wrapped with other frameworks or libraries (e.g., tRPC, NextAuth, Better Auth, etc.)
• Custom handlers that don't use standard Next.js patterns
• Routes that rely on middleware or external schema definitions

For custom authentication, data validation, or RPC patterns, please use targeted libraries designed for those systems.

Development

Prerequisites

• Node.js (v18 or higher recommended)
• pnpm, npm, or bun

Setup

• Install dependencies:

pnpm install

• Run the unit tests:

pnpm run test

• Build the library:

pnpm run build

• Run in development mode with watch:

pnpm run dev

Scripts

• pnpm run build: Build the CLI tool with tsdown
• pnpm run dev: Watch mode for development
• pnpm run test: Run unit tests with Vitest
• pnpm run typecheck: Type-check the TypeScript code
• pnpm run release: Bump version and publish to npm

Repository

• GitHub Repository
• Issues

License

MIT