next-openapi-gen

Automatically generate OpenAPI 3.0 documentation from Next.js projects, with support for TypeScript types and Zod schemas.

Features

• ✅ Automatic OpenAPI documentation generation from Next.js code
• ✅ Support for Next.js App Router (including /api/users/[id]/route.ts routes)
• ✅ TypeScript types support
• ✅ Zod schemas support
• ✅ JSDoc comments support
• ✅ Multiple UI interfaces: Scalar, Swagger, Redoc, Stoplight and Rapidoc available at /api-docs url
• ✅ Path parameters detection (/users/{id})
• ✅ Intelligent parameter examples
• ✅ Intuitive CLI for initialization and documentation generation

Supported interfaces

• Scalar 🆕
• Swagger
• Redoc
• Stoplight Elements
• RapiDoc

Installation

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

Quick Start

1# Initialize OpenAPI configuration
2npx next-openapi-gen init --ui scalar --docs-url api-docs
3
4# Generate OpenAPI documentation
5npx next-openapi-gen generate

Configuration

During initialization (npx next-openapi-gen init), a configuration file next.openapi.json will be created in the project's root directory:

1{
2  "openapi": "3.0.0",
3  "info": {
4    "title": "Next.js API",
5    "version": "1.0.0",
6    "description": "API generated by next-openapi-gen"
7  },
8  "servers": [
9    {
10      "url": "http://localhost:3000",
11      "description": "Local server"
12    }
13  ],
14  "apiDir": "src/app/api",
15  "schemaDir": "src/types", // or "src/schemas" for Zod schemas
16  "schemaType": "typescript", // or "zod" for Zod schemas
17  "outputFile": "openapi.json",
18  "docsUrl": "/api-docs",
19  "includeOpenApiRoutes": false
20}

Configuration Options

Option	Description
apiDir	Path to the API directory
schemaDir	Path to the types/schemas directory
schemaType	Schema type: "typescript" or "zod"
outputFile	Path to the OpenAPI output file
docsUrl	API documentation URL (for Swagger UI)
includeOpenApiRoutes	Whether to include only routes with @openapi tag
defaultResponseSet	Default error response set for all endpoints
responseSets	Named sets of error response codes
errorConfig	Error schema configuration

Documenting Your API

With TypeScript Types

1// src/app/api/users/[id]/route.ts
2
3import { NextRequest, NextResponse } from "next/server";
4
5type UserParams = {
6  id: string; // User ID
7};
8
9type UserResponse = {
10  id: string; // User ID
11  name: string; // Full name
12  email: string; // Email address
13};
14
15/**
16 * Get user information
17 * @description Fetches detailed user information by ID
18 * @pathParams UserParams
19 * @response UserResponse
20 * @openapi

21 */
22export async function GET(
23  request: NextRequest,
24  { params }: { params: { id: string } }
25) {
26  // Implementation...
27}

With Zod Schemas

1// src/app/api/products/[id]/route.ts
2
3import { NextRequest, NextResponse } from "next/server";
4import { z } from "zod";
5
6export const ProductParams = z.object({
7  id: z.string().describe("Product ID"),
8});
9
10export const ProductResponse = z.object({
11  id: z.string().describe("Product ID"),
12  name: z.string().describe("Product name"),
13  price: z.number().positive().describe("Product price"),
14});
15
16/**
17 * Get product information
18 * @description Fetches detailed product information by ID
19 * @pathParams ProductParams
20 * @response ProductResponse
21 * @openapi

22 */
23export async function GET(
24  request: NextRequest,
25  { params }: { params: { id: string } }
26) {
27  // Implementation...
28}

JSDoc Documentation Tags

Tag	Description
@description	Endpoint description
@pathParams	Path parameters type/schema
@params	Query parameters type/schema
@body	Request body type/schema
@bodyDescription	Request body description
@response	Response type/schema
@responseDescription	Response description
@responseSet	Override default response set (public, auth, none)
@add	Add custom response codes (409:ConflictResponse, 429)
@contentType	Request body content type (application/json, multipart/form-data)
@auth	Authorization type (bearer, basic, apikey)
@tag	Custom tag
@deprecated	Marks the route as deprecated
@openapi	Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled)

CLI Usage

1. Initialization

1npx next-openapi-gen init

This command will generate following elements:

• Generate next.openapi.json configuration file
• Install UI interface (default Scalar)
• Add /api-docs page to display OpenAPI documentation

2. Generate Documentation

1npx next-openapi-gen generate

This command will generate OpenAPI documentation based on your API code:

• Scan API directories for routes
• Analyze types/schemas
• Generate OpenAPI file (openapi.json) in public folder
• Create Swagger/Scalar UI endpoint and page (if enabled)

3. View API Documentation

To see API documenation go to http://localhost:3000/api-docs

Examples

Path Parameters

1// src/app/api/users/[id]/route.ts
2
3// TypeScript
4type UserParams = {
5  id: string; // User ID
6};
7
8// Or Zod
9const UserParams = z.object({
10  id: z.string().describe("User ID"),
11});
12
13/**
14 * @pathParams UserParams
15 */
16export async function GET() {
17  // ...
18}

Query Parameters

1// src/app/api/users/route.ts
2
3// TypeScript
4type UsersQueryParams = {
5  page?: number; // Page number
6  limit?: number; // Results per page
7  search?: string; // Search phrase
8};
9
10// Or Zod
11const UsersQueryParams = z.object({
12  page: z.number().optional().describe("Page number"),
13  limit: z.number().optional().describe("Results per page"),
14  search: z.string().optional().describe("Search phrase"),
15});
16
17/**
18 * @params UsersQueryParams
19 */
20export async function GET() {
21  // ...
22}

Request Body

1// src/app/api/users/route.ts
2
3// TypeScript
4type CreateUserBody = {
5  name: string; // Full name
6  email: string; // Email address
7  password: string; // Password
8};
9
10// Or Zod
11const CreateUserBody = z.object({
12  name: z.string().describe("Full name"),
13  email: z.string().email().describe("Email address"),
14  password: z.string().min(8).describe("Password"),
15});
16
17/**
18 * @body CreateUserBody
19 * @bodyDescription User registration data including email and password
20 */
21export async function POST() {
22  // ...
23}

Response

1// src/app/api/users/route.ts
2
3// TypeScript
4type UserResponse = {
5  id: string; // User ID
6  name: string; // Full name
7  email: string; // Email address
8  createdAt: Date; // Creation date
9};
10
11// Or Zod
12const UserResponse = z.object({
13  id: z.string().describe("User ID"),
14  name: z.string().describe("Full name"),
15  email: z.string().email().describe("Email address"),
16  createdAt: z.date().describe("Creation date"),
17});
18
19/**
20 * @response UserResponse
21 * @responseDescription Returns newly created user object
22 */
23export async function GET() {
24  // ...
25}

Authorization

1// src/app/api/protected/route.ts
2
3/**
4 * @auth bearer
5 */
6export async function GET() {
7  // ...
8}

Deprecated

1// src/app/api/v1/route.ts
2
3// TypeScript
4type UserResponse = {
5  id: string;
6  name: string;
7  /** @deprecated Use firstName and lastName instead */
8  fullName?: string;
9  email: string;
10};
11
12// Or Zod
13const UserSchema = z.object({
14  id: z.string(),
15  name: z.string(),
16  fullName: z.string().optional().describe("@deprecated Use name instead"),
17  email: z.string().email(),
18});
19
20/**
21 * @body UserSchema
22 * @response UserResponse
23 */
24export async function GET() {
25  // ...
26}

File Uploads / Multipart Form Data

1// src/app/api/upload/route.ts
2
3// TypeScript
4type FileUploadFormData = {
5  file: File;
6  description?: string;
7  category: string;
8};
9
10// Or Zod
11const FileUploadSchema = z.object({
12  file: z.custom<File>().describe("Image file (PNG/JPG)"),
13  description: z.string().optional().describe("File description"),
14  category: z.string().describe("File category"),
15});
16
17/**
18 * @body FileUploadSchema
19 * @contentType multipart/form-data
20 */
21export async function POST() {
22  // ...
23}

Response Management

Zero Config + Response Sets

Configure reusable error sets in next.openapi.json:

1{
2  "defaultResponseSet": "common",
3  "responseSets": {
4    "common": ["400", "401", "500"],
5    "public": ["400", "500"],
6    "auth": ["400", "401", "403", "500"]
7  }
8}

Usage Examples

1/**
2 * Auto-default responses
3 * @response UserResponse
4 * @openapi

5 */
6export async function GET() {}
7// Generates: 200:UserResponse + common errors (400, 401, 500)
8
9/**
10 * Override response set
11 * @response ProductResponse
12 * @responseSet public
13 * @openapi

14 */
15export async function GET() {}
16// Generates: 200:ProductResponse + public errors (400, 500)
17
18/**
19 * Add custom responses
20 * @response 201:UserResponse
21 * @add 409:ConflictResponse
22 * @openapi

23 */
24export async function POST() {}
25// Generates: 201:UserResponse + common errors + 409:ConflictResponse
26
27/**
28 * Combine multiple sets
29 * @response UserResponse
30 * @responseSet auth,crud
31 * @add 429:RateLimitResponse
32 * @openapi

33 */
34export async function PUT() {}
35// Combines: auth + crud errors + custom 429

Error Schema Configuration

Define consistent error schemas using templates:

1{
2  "errorConfig": {
3    "template": {
4      "type": "object",
5      "properties": {
6        "error": {
7          "type": "string",
8          "example": "{{ERROR_MESSAGE}}"
9        }
10      }
11    },
12    "codes": {
13      "invalid_request": {
14        "description": "Invalid request",
15        "variables": { "ERROR_MESSAGE": "Validation failed" }
16      }
17    }
18  }
19}

Advanced Usage

Automatic Path Parameter Detection

The library automatically detects path parameters and generates documentation for them:

1// src/app/api/users/[id]/posts/[postId]/route.ts
2
3// Will automatically detect 'id' and 'postId' parameters
4export async function GET() {
5  // ...
6}

If no type/schema is provided for path parameters, a default schema will be generated.

Intelligent Examples

The library generates intelligent examples for parameters based on their name:

Parameter name	Example
id, *Id	"123" or 123
slug	"example-slug"
uuid	"123e4567-e89b-12d3-a456-426614174000"
email	"user@example.com"
name	"example-name"
date	"2023-01-01"

Advanced Zod Features

The library supports advanced Zod features such as:

Validation Chains

1// Zod validation chains are properly converted to OpenAPI schemas
2const EmailSchema = z
3  .string()
4  .email()
5  .min(5)
6  .max(100)
7  .describe("Email address");
8
9// Converts to OpenAPI with email format, minLength and maxLength

Type Aliases with z.infer

1// You can use TypeScript with Zod types
2import { z } from "zod";
3
4const UserSchema = z.object({
5  id: z.string().uuid(),
6  name: z.string().min(2),
7});
8
9// Use z.infer to create a TypeScript type
10type User = z.infer<typeof UserSchema>;
11
12// The library will be able to recognize this schema by reference `UserSchema` or `User` type.

Available UI providers

License

MIT