stevenlafl/next-openapi-gen

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

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,
  "debug": 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
defaultResponseSet	Default error response set for all endpoints
responseSets	Named sets of error response codes
errorConfig	Error schema configuration
debug	Enable detailed logging during generation

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

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() {
  // ...
}

File Uploads / Multipart Form Data

// src/app/api/upload/route.ts

// TypeScript
type FileUploadFormData = {
  file: File;
  description?: string;
  category: string;
};

// Or Zod
const FileUploadSchema = z.object({
  file: z.custom<File>().describe("Image file (PNG/JPG)"),
  description: z.string().optional().describe("File description"),
  category: z.string().describe("File category"),
});

/**
 * @body FileUploadSchema
 * @contentType multipart/form-data
 */
export async function POST() {
  // ...
}

Response Management

Zero Config + Response Sets

Configure reusable error sets in next.openapi.json:

{
  "defaultResponseSet": "common",
  "responseSets": {
    "common": ["400", "401", "500"],
    "public": ["400", "500"],
    "auth": ["400", "401", "403", "500"]
  }
}

Usage Examples

/**
 * Auto-default responses
 * @response UserResponse
 * @openapi
 */
export async function GET() {}
// Generates: 200:UserResponse + common errors (400, 401, 500)

/**
 * Override response set
 * @response ProductResponse
 * @responseSet public
 * @openapi
 */
export async function GET() {}
// Generates: 200:ProductResponse + public errors (400, 500)

/**
 * Add custom responses
 * @response 201:UserResponse
 * @add 409:ConflictResponse
 * @openapi
 */
export async function POST() {}
// Generates: 201:UserResponse + common errors + 409:ConflictResponse

/**
 * Combine multiple sets
 * @response UserResponse
 * @responseSet auth,crud
 * @add 429:RateLimitResponse
 * @openapi
 */
export async function PUT() {}
// Combines: auth + crud errors + custom 429

Error Schema Configuration

Define consistent error schemas using templates:

{
  "errorConfig": {
    "template": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "example": "{{ERROR_MESSAGE}}"
        }
      }
    },
    "codes": {
      "invalid_request": {
        "description": "Invalid request",
        "variables": { "ERROR_MESSAGE": "Validation failed" }
      }
    }
  }
}

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