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

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

Quick Start

# Initialize OpenAPI configuration
npx next-openapi-gen init --ui scalar --docs-url api-docs

# Generate OpenAPI documentation
npx 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:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Next.js API",
    "version": "1.0.0",
    "description": "API generated by next-openapi-gen"
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "Local server"
    }
  ],
  "apiDir": "src/app/api",
  "schemaDir": "src/types", // or "src/schemas" for Zod schemas
  "schemaType": "typescript", // or "zod" for Zod schemas
  "outputFile": "openapi.json",
  "docsUrl": "/api-docs",
  "includeOpenApiRoutes": false
}

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

Documenting Your API

With TypeScript Types

// src/app/api/users/[id]/route.ts

import { NextRequest, NextResponse } from "next/server";

type UserParams = {
  id: string; // User ID
};

type UserResponse = {
  id: string; // User ID
  name: string; // Full name
  email: string; // Email address
};

/**
 * Get user information
 * @description Fetches detailed user information by ID
 * @pathParams UserParams
 * @response UserResponse
 * @openapi
 */
export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  // Implementation...
}

With Zod Schemas

// src/app/api/products/[id]/route.ts

import { NextRequest, NextResponse } 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().describe("Product ID"),
  name: z.string().describe("Product name"),
  price: z.number().positive().describe("Product price"),
});

/**
 * Get product information
 * @description Fetches detailed product information by ID
 * @pathParams ProductParams
 * @response ProductResponse
 * @openapi
 */
export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  // Implementation...
}

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
@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

npx 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

npx 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

// src/app/api/users/[id]/route.ts

// TypeScript
type UserParams = {
  id: string; // User ID
};

// Or Zod
const UserParams = z.object({
  id: z.string().describe("User ID"),
});

/**
 * @pathParams UserParams
 */
export async function GET() {
  // ...
}

Query Parameters

// src/app/api/users/route.ts

// TypeScript
type UsersQueryParams = {
  page?: number; // Page number
  limit?: number; // Results per page
  search?: string; // Search phrase
};

// Or Zod
const UsersQueryParams = z.object({
  page: z.number().optional().describe("Page number"),
  limit: z.number().optional().describe("Results per page"),
  search: z.string().optional().describe("Search phrase"),
});

/**
 * @params UsersQueryParams
 */
export async function GET() {
  // ...
}

Request Body

// src/app/api/users/route.ts

// TypeScript
type CreateUserBody = {
  name: string; // Full name
  email: string; // Email address
  password: string; // Password
};

// Or Zod
const CreateUserBody = z.object({
  name: z.string().describe("Full name"),
  email: z.string().email().describe("Email address"),
  password: z.string().min(8).describe("Password"),
});

/**
 * @body CreateUserBody
 * @bodyDescription User registration data including email and password
 */
export async function POST() {
  // ...
}

Response

// src/app/api/users/route.ts

// TypeScript
type UserResponse = {
  id: string; // User ID
  name: string; // Full name
  email: string; // Email address
  createdAt: Date; // Creation date
};

// Or Zod
const UserResponse = z.object({
  id: z.string().describe("User ID"),
  name: z.string().describe("Full name"),
  email: z.string().email().describe("Email address"),
  createdAt: z.date().describe("Creation date"),
});

/**
 * @response UserResponse
 * @responseDescription Returns newly created user object
 */
export async function GET() {
  // ...
}

Authorization

// src/app/api/protected/route.ts

/**
 * @auth bearer
 */
export async function GET() {
  // ...
}

Deprecated

// src/app/api/v1/route.ts

// TypeScript
type UserResponse = {
  id: string;
  name: string;
  /** @deprecated Use firstName and lastName instead */
  fullName?: string;
  email: string;
};

// Or Zod
const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  fullName: z.string().optional().describe("@deprecated Use name instead"),
  email: z.string().email(),
});

/**
 * @body UserSchema
 * @response UserResponse
 */
export async function GET() {
  // ...
}

Advanced Usage

Automatic Path Parameter Detection

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

// src/app/api/users/[id]/posts/[postId]/route.ts

// Will automatically detect 'id' and 'postId' parameters
export async function GET() {
  // ...
}

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

// Zod validation chains are properly converted to OpenAPI schemas
const EmailSchema = z
  .string()
  .email()
  .min(5)
  .max(100)
  .describe("Email address");

// Converts to OpenAPI with email format, minLength and maxLength

Type Aliases with z.infer

// You can use TypeScript with Zod types
import { z } from "zod";

const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(2),
});

// Use z.infer to create a TypeScript type
type User = z.infer<typeof UserSchema>;

// The library will be able to recognize this schema by reference `UserSchema` or `User` type.

Available UI providers

Scalar	Swagger	Redoc	Stoplight Elements	RapiDoc

License

MIT