next-openapi-gen 0.3.3 → 0.4.1

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
+## Installation
 
-- **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.
+```bash
+npm install next-openapi-gen --save-dev
+```
 
-## Installation
+## Quick Start
 
 ```bash
-yarn add next-openapi-gen
+# Initialize OpenAPI configuration
+npx next-openapi-gen init --ui scalar --docs-url api-docs
+
+# Generate OpenAPI documentation
+npx next-openapi generate
+```
+
+## Configuration
+
+During initialization (`npx next-openapi 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
+}
+```
+
+### 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...
+}
+```
+
+### 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...
+}
 ```
 
-## Usage
+## JSDoc Documentation Tags
+
+| 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) |
 
-### Step 1: Initialize Configuration and Setup
+## CLI Usage
 
-Run the following command to generate the `next.openapi.json` configuration file and automatically set up Scalar UI with `/api-docs` routes:
+### 1. Initialization
 
 ```bash
-npx next-openapi-gen init --ui scalar --docs-url api-docs
+npx next-openapi init
 ```
 
-Parameters:
-- **ui**: `scalar` | `swagger` | `redoc` | `stoplight` | `rapidoc`
-- **docs-url**: url on which api docs will be visible
+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
 
-This command does the following:
+### 2. Generate Documentation
 
-- 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.
+```bash
+npx next-openapi generate
+```
 
-### Step 2: Add JSDoc Comments to Your API Routes
+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)
 
-Annotate your API routes using JSDoc comments. Here's an example:
+### 3. View API Documentation
 
-<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>
+To see API documenation go to `http://localhost:3000/api-docs` 
 
-### Step 3: Generate the OpenAPI Specification
+## Examples
 
-Run the following command to generate the OpenAPI schema based on your API routes:
+### Path Parameters
 
-```bash
-npx next-openapi-gen generate
+```typescript
+// 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
+
+```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() {
+  // ...
+}
+```
+
+### 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() {
+  // ...
+}
+```
+
+### 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() {
+  // ...
+}
 ```
 
-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.
+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:
 
-### Step 4: View API Documentation
+| 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"` |
 
-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`.
+## Advanced Zod Features
 
-## JSDoc tags
+The library supports advanced Zod features such as:
 
-- `@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.
+### 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
+```
 
-## Configuration Options
+### Type Aliases with z.infer
 
-The `next.openapi.json` file allows you to configure the behavior of the OpenAPI generator, including options such as:
+```typescript
+// You can use TypeScript with Zod types
+import { z } from 'zod';
 
-- **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.
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(2)
+});
 
-## Interface providers
+// 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

@@ -1,7 +1,7 @@
 import path from "path";
 import fs from "fs";
-import { RouteProcessor } from "./route-processor.js";
-import { cleanSpec } from "./utils.js";
+import { RouteProcessor } from "./route-processor";
+import { cleanSpec } from "./utils";
 export class OpenApiGenerator {
     config;
     template;
@@ -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;
     }