@bernierllc/nextjs-openapi

Next.js-specific OpenAPI generation with App Router and Pages Router support.

Features

- Dual Router Support: Full support for both App Router (app/) and Pages Router (pages/)
- Automatic Discovery: Discovers API routes in your Next.js project
- Metadata Extraction: Extracts JSDoc annotations, Zod schemas, and Next.js runtime config
- File Watching: Development mode with hot reload
- TypeScript First: Full TypeScript support with strict typing
- NeverHub Integration: Optional real-time event publishing

Installation

``bash
npm install @bernierllc/nextjs-openapi
`

Usage

$3

`typescript
import { NextJSOpenAPIGenerator } from '@bernierllc/nextjs-openapi';

const generator = new NextJSOpenAPIGenerator({
projectRoot: './my-nextjs-app',
appDir: 'app',
pagesDir: 'pages',
sources: {
jsdoc: {
enabled: true,
patterns: ['/.ts', '/.tsx'],
includeMiddleware: true
},
metadata: {
enabled: true,
includeRuntime: true
}
},
output: {
json: 'public/openapi.json',
yaml: 'public/openapi.yaml'
}
});

// Generate OpenAPI specification
const result = await generator.generate();
console.log('Generated spec:', result.spec);
`

$3

`typescript
// app/api/users/route.ts

/**
* @openapi
* /api/users:
* get:
* summary: List all users
* description: Retrieve a list of all users
*/
export async function GET() {
return Response.json({ users: [] });
}

/**
* @openapi
* /api/users:
* post:
* summary: Create a user
* description: Create a new user
*/
export async function POST() {
return Response.json({ id: '1' });
}

export const runtime = 'edge';
export const dynamic = 'force-dynamic';
`

$3

`typescript
// pages/api/products.ts

/**
* @openapi
* /api/products:
* get:
* summary: List all products
* description: Retrieve a list of all products
*/
export default function handler(req, res) {
if (req.method === 'GET') {
return res.json({ products: [] });
}
return res.status(405).end();
}
`

$3

Both App Router and Pages Router dynamic segments are automatically converted to OpenAPI path parameters:

`typescript
// app/api/users/[id]/route.ts
// Generates: /api/users/{id}

export async function GET(request: Request, { params }: { params: { id: string } }) {
return Response.json({ id: params.id });
}
`

$3

`typescript
const watcher = generator.watch((result) => {
console.log('OpenAPI updated:', result.spec.info);
console.log('Routes:', Object.keys(result.spec.paths));
});

// Later...
watcher.stop();
`

$3

`typescript
// Discover all API routes
const allRoutes = await generator.discoverAPIRoutes();

// Discover App Router routes only
const appRoutes = await generator.discoverAppRoutes();

// Discover Pages Router routes only
const pagesRoutes = await generator.discoverPagesRoutes();
`

Configuration

$3

`typescript
interface NextJSOpenAPIConfig {
projectRoot: string; // Next.js project root
appDir?: string; // App Router directory (default: 'app')
pagesDir?: string; // Pages Router directory (default: 'pages')
sources: NextJSSourceConfig; // Documentation sources
output: NextJSOutputConfig; // Output configuration
development?: NextJSDevelopmentConfig; // Dev options
build?: NextJSBuildConfig; // Build options
}
`

$3

`typescript
interface NextJSSourceConfig {
jsdoc?: {
enabled: boolean;
patterns: string[]; // File patterns to scan
includeMiddleware?: boolean; // Include middleware docs
};
zod?: {
enabled: boolean;
schemasPath: string; // Zod schemas directory
metadataPattern: string; // Metadata export pattern
};
metadata?: {
enabled: boolean;
includeRuntime?: boolean; // Include runtime config
includePerformance?: boolean; // Include performance hints
};
}
`

Runtime Configuration Support

The generator automatically extracts Next.js runtime configuration:

`typescript
export const runtime = 'edge'; // Runtime mode
export const dynamic = 'force-dynamic'; // Dynamic behavior
export const revalidate = 60; // Revalidation period
`

API

$3

Generate complete OpenAPI specification.

$3

Discover all API routes (both App Router and Pages Router).

$3

Discover App Router routes only.

$3

Discover Pages Router routes only.

$3

Extract metadata from a specific route.

$3

Watch for file changes and regenerate on changes.

$3

Watch API routes only.

Dependencies

- @bernierllc/openapi-generator - Core OpenAPI generation
- @bernierllc/route-discoverer - Route discovery
- @bernierllc/jsdoc-openapi-parser - JSDoc parsing
- @bernierllc/zod-openapi-converter - Zod schema conversion
- @bernierllc/file-handler - File operations
- @bernierllc/logger - Logging
- @bernierllc/neverhub-adapter - Event publishing
- chokidar` - File watching

License

Copyright (c) 2025 Bernier LLC. See LICENSE file for details.