next-openapi-gen 0.3.3 → 0.4.2

package/README.md

@@ -1,13 +1,20 @@
 # next-openapi-gen
 
-**next-openapi-gen** super fast and easy way to generate OpenAPI 3.0 documentation automatically from API routes in NextJS.
+Automatically generate OpenAPI 3.0 documentation from Next.js projects, with support for both TypeScript types and Zod schemas.
 
-## Prerequisites
+## Features
 
-- Next.js >= 14
-- Node >= 18
+- ✅ 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
 
-## Interfaces
+## Supported interfaces
 
 - Scalar 🆕
 - Swagger
@@ -15,182 +22,350 @@
 - Stoplight Elements
 - RapiDoc
 
-## Features
-
-- **Automatic OpenAPI Generation**: Generate OpenAPI 3.0 documentation from your Next.js routes, automatically parsing TypeScript types for parameters, request bodies and responses. Field comments in TypeScript types are reflected as descriptions in the OpenAPI schema.
-- **Complex TypeScript Types**: Use complex TypeScript types, such as `nested objects`, `arrays`, `enums` and `unions` (mapped to anyOf). This enables a more comprehensive representation of data structures directly in the OpenAPI schema.
-- **JSDoc-Based Documentation**: Document API routes with optional JSDoc comments, including tags like `@openapi`, `@auth`, `@desc`, `@params`, `@body`, and `@response` to easily define route metadata.
-- **Multiple UI Interfaces**: Choose between `Scalar`, `Swagger UI`, `Redoc`, `Stoplight Elements` or `RapiDoc` to visualize your API documentation. Customize the interface to fit your preferences.
-- **Real-time Documentation**: As your API evolves, regenerate the OpenAPI documentation with a single command, ensuring your documentation is always up to date.
-- **Easy configuration**: Customize generator behavior using the `next.openapi.json` configuration file, allowing for quick adjustments without modifying the code.
-
 ## Installation
 
 ```bash
-yarn add next-openapi-gen
+npm install next-openapi-gen --save-dev
 ```
 
-## Usage
-
-### Step 1: Initialize Configuration and Setup
-
-Run the following command to generate the `next.openapi.json` configuration file and automatically set up Scalar UI with `/api-docs` routes:
+## Quick Start
 
 ```bash
+# Initialize OpenAPI configuration
 npx next-openapi-gen init --ui scalar --docs-url api-docs
+
+# Generate OpenAPI documentation
+npx next-openapi-gen generate
 ```
 
-Parameters:
-- **ui**: `scalar` | `swagger` | `redoc` | `stoplight` | `rapidoc`
-- **docs-url**: url on which api docs will be visible
+## Configuration
+
+During initialization (`npx next-openapi-gen init`), a configuration file `next.openapi.json` will be created in the project's root directory:
+
+```json
+{
+  "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",
+  "schemaType": "typescript",  // or "zod" for Zod schemas
+  "outputFile": "openapi.json",
+  "docsUrl": "/api-docs",
+  "includeOpenApiRoutes": false
+}
+```
 
-This command does the following:
+### 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
+
+```typescript
+// 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
+ * @desc Fetches detailed user information by ID
+ * @pathParams UserParams
+ * @response UserResponse
+ * @openapi
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  // Implementation...
+}
+```
 
-- Generates a `next.openapi.json` file, which stores the OpenAPI configuration for your project.
-- Installs Scalar UI to provide an API documentation interface.
-- Adds an `/api-docs` route in the Next.js app for visualizing the generated OpenAPI documentation.
+### With Zod Schemas
+
+```typescript
+// 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
+ * @desc Fetches detailed product information by ID
+ * @pathParams ProductParams
+ * @response ProductResponse
+ * @openapi
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  // Implementation...
+}
+```
 
-### Step 2: Add JSDoc Comments to Your API Routes
+## JSDoc Documentation Tags
 
-Annotate your API routes using JSDoc comments. Here's an example:
+| Tag | Description |
+|-----|------|
+| `@desc` | Endpoint description |
+| `@pathParams` | Path parameters type/schema |
+| `@params` | Query parameters type/schema |
+| `@body` | Request body type/schema |
+| `@response` | Response type/schema |
+| `@auth` | Authorization type (`bearer`, `basic`, `apikey`) |
+| `@openapi` | Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled) |
 
-<div align="center">
-  <table>
-    <tr>
-      <th>Login route</th>
-      <th>Scalar / Swagger</th>
-    </tr>
-    <tr>
-      <td>
-
-  ```typescript
-  //app/api/auth/login/route.ts
-
-  type LoginBody = {
-    email: string; // user email
-    password: string; // user password
-  };
-
-  type LoginResponse = {
-    token: string; // auth token
-    refresh_token: string; // refresh token
-  };
-
-  /**
-   * Authenticate as a user.
-   * @desc: Login a user
-   * @body: LoginBody
-   * @response: LoginResponse
-   */
-  export async function POST(req: Request) {
-    ...
-  }
-  ```
-  </td>
-  <td>
-    <img width="340" alt="api-login-scalar" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-login-scalar.png" alt-text="api-login"/>
-    <br/><br/><br/>
-    <img width="340" alt="api-login-swagger" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-login-swagger.png" alt-text="api-login-swagger"/>
-  </td>
-  </tr>
-
-  <tr>
-      <th>Users route</th>
-      <th>Scalar / Swagger</th>
-    </tr>
-  <tr>
-      <td>
-
-  ```typescript
-  //app/api/users/route.ts
-
-  enum ROLE {
-    OWNER,
-    MEMBER,
-  }
-
-  type User = {
-    id: number;
-    name: string;
-    email: string;
-    role: ROLE;
-    address: Address;
-  };
-
-  type Address = {
-    line1: string;
-    line2?: string;
-    city: string;
-    postalCode: string;
-  };
-
-  type UsersParams = {
-    search: string; // search by
-    role?: ROLE; // filter by role
-    page?: number; // page number
-  };
-
-  type UsersResponse = {
-    page?: number;
-    count?: number;
-    data: User[];
-  };
-
-  /**
-   * List all users.
-   * @auth: bearer
-   * @params: UsersParams
-   * @response: UsersResponse
-   */
-  export async function GET(req: Request) {
-    ...
-  }
-  ```
-  </td>
-  <td>
-    <img width="340" alt="api-users-scalar" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-users-scalar.png" alt-text="api-users-scalar"/>
-    <br/><br/><br/>
-    <img width="340" alt="api-users-swagger" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-users-swagger.png" alt-text="api-users-swagger"/>
-  </td>
-  </tr>
-</table>
-</div>
+## CLI Usage
 
-### Step 3: Generate the OpenAPI Specification
+### 1. Initialization
 
-Run the following command to generate the OpenAPI schema based on your API routes:
+```bash
+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
 
 ```bash
 npx next-openapi-gen generate
 ```
 
-This command processes all your API routes, extracts the necessary information from JSDoc comments, and generates the OpenAPI schema, typically saved to a `openapi.json` file in the `public` folder.
+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
 
-### Step 4: View API Documentation
+### Path Parameters
 
-With the `/api-docs` route generated from the init command, you can now access your API documentation through Scalar UI by navigating to `http://localhost:3000/api-docs`.
+```typescript
+// src/app/api/users/[id]/route.ts
 
-## JSDoc tags
+// TypeScript
+type UserParams = {
+  id: string; // User ID
+};
 
-- `@openapi`: Marks the route for inclusion in the OpenAPI specification.
-- `@auth`: Specifies authentication type used for API route (`basic`, `bearer`, `apikey`).
-- `@desc`: Provides a detailed description of the API route.
-- `@params`: Specifies the TypeScript interface for the query parameters.
-- `@body`: Specifies the TypeScript interface for the request body.
-- `@response`: Specifies the TypeScript interface for the response.
+// Or Zod
+const UserParams = z.object({
+  id: z.string().describe("User ID")
+});
 
-## Configuration Options
+/**
+ * @pathParams UserParams
+ */
+export async function GET() {
+  // ...
+}
+```
 
-The `next.openapi.json` file allows you to configure the behavior of the OpenAPI generator, including options such as:
+### Query Parameters
+
+```typescript
+// 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() {
+  // ...
+}
+```
 
-- **apiDir**: (default: `./src/app/api`) The directory where your API routes are stored.
-- **schemaDir**: (default: `./src`) The directory where your schema definitions are stored.
-- **docsUrl**: (default: `./api-docs`) Route where OpenAPI UI is available.
-- **ui**: (default: `scalar`) OpenAPI UI interface.
-- **outputFile**: (default: `./openapi.json`) The file where the generated OpenAPI specification will be saved in `public` folder.
-- **includeOpenApiRoutes**: (default: `false`) When `true`, the generator will only include routes that have the `@openapi` tag in their JSDoc comments.
+### Request Body
+
+```typescript
+// 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
+ */
+export async function POST() {
+  // ...
+}
+```
 
-## Interface providers
+### Response
+
+```typescript
+// 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
+ */
+export async function GET() {
+  // ...
+}
+```
+
+### Authorization
+
+```typescript
+// src/app/api/protected/route.ts
+
+/**
+ * @auth bearer
+ */
+export async function GET() {
+  // ...
+}
+```
+
+## Advanced Usage
+
+### Automatic Path Parameter Detection
+
+The library automatically detects path parameters and generates documentation for them:
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+```
+
+## Available UI providers
 
 <div align="center">
 <table>
@@ -221,3 +396,8 @@ The `next.openapi.json` file allows you to configure the behavior of the OpenAPI
    </tr>
   </tbody>
 </table>
+</div>
+
+## License
+
+MIT

package/dist/components/scalar.js

@@ -1,20 +1,20 @@
 export const scalarDeps = ["@scalar/api-reference-react", "ajv"];
 export function ScalarUI(outputFile) {
-    return `
-"use client";
-
-import { ApiReferenceReact } from "@scalar/api-reference-react";
-
-import "@scalar/api-reference-react/style.css";
-
-export default function ApiDocsPage() {
-  return (
-    <ApiReferenceReact
-      configuration={{
-        url: "/${outputFile}",
-      }}
-    />
-  );
-}
+    return `
+"use client";
+
+import { ApiReferenceReact } from "@scalar/api-reference-react";
+
+import "@scalar/api-reference-react/style.css";
+
+export default function ApiDocsPage() {
+  return (
+    <ApiReferenceReact
+      configuration={{
+        url: "/${outputFile}",
+      }}
+    />
+  );
+}
 `;
 }

package/dist/lib/openapi-generator.js

@@ -14,7 +14,7 @@ export class OpenApiGenerator {
     }
     getConfig() {
         // @ts-ignore
-        const { apiDir, schemaDir, docsUrl, ui, outputFile, includeOpenApiRoutes } = this.template;
+        const { apiDir, schemaDir, docsUrl, ui, outputFile, includeOpenApiRoutes, schemaType = "typescript", } = this.config;
         return {
             apiDir,
             schemaDir,
@@ -22,12 +22,51 @@ export class OpenApiGenerator {
             ui,
             outputFile,
             includeOpenApiRoutes,
+            schemaType,
         };
     }
     generate() {
         const { apiDir } = this.config;
+        // Check if app router structure exists
+        let appRouterApiDir = "";
+        if (fs.existsSync(path.join(path.dirname(apiDir), "app", "api"))) {
+            appRouterApiDir = path.join(path.dirname(apiDir), "app", "api");
+            console.log(`Found app router API directory at ${appRouterApiDir}`);
+        }
+        // Scan pages router routes
         this.routeProcessor.scanApiRoutes(apiDir);
+        // If app router directory exists, scan it as well
+        if (appRouterApiDir) {
+            this.routeProcessor.scanApiRoutes(appRouterApiDir);
+        }
         this.template.paths = this.routeProcessor.getSwaggerPaths();
+        // Add server URL for examples if not already defined
+        if (!this.template.servers || this.template.servers.length === 0) {
+            this.template.servers = [
+                {
+                    url: this.template.basePath || "",
+                    description: "API server",
+                },
+            ];
+        }
+        // Ensure there's a components section if not already defined
+        if (!this.template.components) {
+            this.template.components = {};
+        }
+        // Add schemas section if not already defined
+        if (!this.template.components.schemas) {
+            this.template.components.schemas = {};
+        }
+        // Get defined schemas from the processor
+        const definedSchemas = this.routeProcessor
+            .getSchemaProcessor()
+            .getDefinedSchemas();
+        if (definedSchemas && Object.keys(definedSchemas).length > 0) {
+            this.template.components.schemas = {
+                ...this.template.components.schemas,
+                ...definedSchemas,
+            };
+        }
         const openapiSpec = cleanSpec(this.template);
         return openapiSpec;
     }

package/dist/lib/route-processor.js

@@ -18,6 +18,12 @@ export class RouteProcessor {
         this.config = config;
         this.schemaProcessor = new SchemaProcessor(config.schemaDir);
     }
+    /**
+     * Get the SchemaProcessor instance
+     */
+    getSchemaProcessor() {
+        return this.schemaProcessor;
+    }
     isRoute(varName) {
         return HTTP_METHODS.includes(varName);
     }
@@ -39,8 +45,16 @@ export class RouteProcessor {
                     if (this.isRoute(declaration.id.name)) {
                         // Don't bother adding routes for processing if only including OpenAPI routes and the route is not OpenAPI
                         if (!this.config.includeOpenApiRoutes ||
-                            (this.config.includeOpenApiRoutes && dataTypes.isOpenApi))
+                            (this.config.includeOpenApiRoutes && dataTypes.isOpenApi)) {
+                            // Check for URL parameters in the route path
+                            const routePath = this.getRoutePath(filePath);
+                            const pathParams = extractPathParameters(routePath);
+                            // If we have path parameters but no pathParamsType defined, we should log a warning
+                            if (pathParams.length > 0 && !dataTypes.pathParams) {
+                                console.warn(`Route ${routePath} contains path parameters ${pathParams.join(", ")} but no @pathParams type is defined.`);
+                            }
                             this.addRouteToPaths(declaration.id.name, filePath, dataTypes);
+                        }
                     }
                 }
                 if (t.isVariableDeclaration(declaration)) {
@@ -50,8 +64,14 @@ export class RouteProcessor {
                                 const dataTypes = extractJSDocComments(path);
                                 // Don't bother adding routes for processing if only including OpenAPI routes and the route is not OpenAPI
                                 if (!this.config.includeOpenApiRoutes ||
-                                    (this.config.includeOpenApiRoutes && dataTypes.isOpenApi))
+                                    (this.config.includeOpenApiRoutes && dataTypes.isOpenApi)) {
+                                    const routePath = this.getRoutePath(filePath);
+                                    const pathParams = extractPathParameters(routePath);
+                                    if (pathParams.length > 0 && !dataTypes.pathParams) {
+                                        console.warn(`Route ${routePath} contains path parameters ${pathParams.join(", ")} but no @pathParams type is defined.`);
+                                    }
                                     this.addRouteToPaths(decl.id.name, filePath, dataTypes);
+                                }
                             }
                         }
                     });
@@ -103,6 +123,7 @@ export class RouteProcessor {
             summary: summary,
             description: description,
             tags: [rootPath],
+            parameters: [],
         };
         // Add auth
         if (auth) {
@@ -112,7 +133,6 @@ export class RouteProcessor {
                 },
             ];
         }
-        definition.parameters = [];
         if (params) {
             definition.parameters =
                 this.schemaProcessor.createRequestParamsSchema(params);