@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

npm install @bernierllc/nextjs-openapi

Usage

Basic Setup

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);

App Router Example

// 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';

Pages Router Example

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

Dynamic Routes

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

// 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 });
}

Watch Mode

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

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

Discover Routes Only

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

NextJSOpenAPIConfig

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
}

Source Configuration

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:

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

API

generate(): Promise<NextJSGenerationResult>

Generate complete OpenAPI specification.

discoverAPIRoutes(): Promise<NextJSAPIRoute[]>

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

discoverAppRoutes(): Promise<NextJSAppRoute[]>

Discover App Router routes only.

discoverPagesRoutes(): Promise<NextJSPagesRoute[]>

Discover Pages Router routes only.

extractRouteMetadata(route): Promise<NextJSRouteMetadata>

Extract metadata from a specific route.

watch(callback): NextJSWatcher

Watch for file changes and regenerate on changes.

watchAPIRoutes(callback): NextJSWatcher

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.