next-openapi-gen 0.0.15 → 0.0.18

package/README.md

@@ -1,125 +1,155 @@
-# next-openapi-gen
-
-**next-openapi-gen** super fast and easy way to generate OpenAPI 3.0 documentation automatically from API routes in a Next.js 14.
-
-With support for multiple user interfaces next-openapi-gen makes documenting your API a breeze!
-
-## Prerequisites
-
-- Nextjs >= 14
-- Node >= 18
-
-## Supported interfaces
-
-- Swagger
-- Redoc
-- 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.
-- **TypeScript Type Scanning**: Automatically resolve TypeScript types for params, body, and responses based on your API endpoint's TypeScript definitions. Field comments in TypeScript types are reflected as descriptions in the OpenAPI schema.
-- **JSDoc-Based Documentation (Optional)**:  Document API routes with JSDoc comments, including tags like `@openapi`, `@auth`, `@desc`, `@params`, `@body`, and `@response` to easily define route metadata.
-- **UI Interface Options**: Choose between `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
-```
-
-## Usage
-
-### Step 1: Initialize Configuration and Setup
-
-Run the following command to generate the `next.openapi.json` configuration file and automatically set up Swagger UI with `/api-docs` routes:
-
-```bash
-npx next-openapi-gen init --ui swagger --docs-url api-docs
-```
-
-Parameters:
-- **ui**: `swagger` | `redoc` | `stoplight` | `rapidoc`
-- **docs-url**: url on which api docs will be visible
-
-This command does the following:
-
-- Generates a `next.openapi.json` file, which stores the OpenAPI configuration for your project.
-- Installs Swagger UI to provide an API documentation interface.
-- Adds an `/api-docs` route in the Next.js app for visualizing the generated OpenAPI documentation.
-
-### Step 2: Add JSDoc Comments to Your API Routes
-
-Annotate your API routes using JSDoc comments. Here's an example:
-
-```typescript
-//app/api/auth/reset-password/route.ts
-
-import { type NextRequest } from "next/server";
-
-type ResetPasswordParams = {
-  token: string; // Token for resetting the password
-};
-
-type ResetPasswordBody = {
-  password: string; // The new password for the user
-};
-
-type ResetPasswordResponse = {
-  message: string; // Confirmation message that password has been reset
-};
-
-/**
- * Reset the user's password.
- * @auth: bearer
- * @desc: Allows users to reset their password using a reset token.
- * @params: ResetPasswordParams
- * @body: ResetPasswordBody
- * @response: ResetPasswordResponse
- */
-export async function POST(req: Request) {
-  const searchParams = req.nextUrl.searchParams;
-
-  const token = searchParams.get("token"); // Token from query params
-  const { password } = await req.json(); // New password from request body
-
-  // Logic to reset the user's password
-
-  return Response.json({ message: "Password has been reset" });
-}
-```
-
-- `@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 or Zod schema for the query parameters.
-- `@body`: Specifies the TypeScript interface or Zod schema for the request body.
-- `@response`: Specifies the TypeScript interface or Zod schema for the response.
-
-### Step 3: Generate the OpenAPI Specification
-
-Run the following command to generate the OpenAPI schema based on your API routes:
-
-```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 `swagger.json` file in the `public` folder.
-
-### Step 4: View API Documentation
-
-With the `/api-docs` route generated from the init command, you can now access your API documentation through Swagger UI by navigating to `http://localhost:3000/api-docs`.
-
-## Configuration Options
-
-The `next.openapi.json` file allows you to configure the behavior of the OpenAPI generator, including options such as:
-
-- **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: `swagger`) OpenAPI UI interface.
-- **outputFile**: (default: `./swagger.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.
+# next-openapi-gen
+
+**next-openapi-gen** super fast and easy way to generate OpenAPI 3.0 documentation automatically from API routes in a Next.js 14.
+
+With support for multiple user interfaces next-openapi-gen makes documenting your API a breeze!
+
+## Prerequisites
+
+- Nextjs >= 14
+- Node >= 18
+
+## Supported interfaces
+
+- Swagger
+- Redoc
+- 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.
+- **TypeScript Type Scanning**: Automatically resolve TypeScript types for params, body, and responses based on your API endpoint's TypeScript definitions. Field comments in TypeScript types are reflected as descriptions in the OpenAPI schema.
+- **JSDoc-Based Documentation (Optional)**:  Document API routes with JSDoc comments, including tags like `@openapi`, `@auth`, `@desc`, `@params`, `@body`, and `@response` to easily define route metadata.
+- **UI Interface Options**: Choose between `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.
+
+![Demo File](https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/demo.gif)
+
+## Installation
+
+```bash
+yarn add next-openapi-gen
+```
+
+## Usage
+
+### Step 1: Initialize Configuration and Setup
+
+Run the following command to generate the `next.openapi.json` configuration file and automatically set up Swagger UI with `/api-docs` routes:
+
+```bash
+npx next-openapi-gen init --ui swagger --docs-url api-docs
+```
+
+Parameters:
+- **ui**: `swagger` | `redoc` | `stoplight` | `rapidoc`
+- **docs-url**: url on which api docs will be visible
+
+This command does the following:
+
+- Generates a `next.openapi.json` file, which stores the OpenAPI configuration for your project.
+- Installs Swagger UI to provide an API documentation interface.
+- Adds an `/api-docs` route in the Next.js app for visualizing the generated OpenAPI documentation.
+
+### Step 2: Add JSDoc Comments to Your API Routes
+
+Annotate your API routes using JSDoc comments. Here's an example:
+
+```typescript
+//app/api/auth/reset-password/route.ts
+
+import { type NextRequest } from "next/server";
+
+type ResetPasswordParams = {
+  token: string; // Token for resetting the password
+};
+
+type ResetPasswordBody = {
+  password: string; // The new password for the user
+};
+
+type ResetPasswordResponse = {
+  message: string; // Confirmation message that password has been reset
+};
+
+/**
+ * Reset the user's password.
+ * @auth: bearer
+ * @desc: Allows users to reset their password using a reset token.
+ * @params: ResetPasswordParams
+ * @body: ResetPasswordBody
+ * @response: ResetPasswordResponse
+ */
+export async function POST(req: Request) {
+  const searchParams = req.nextUrl.searchParams;
+
+  const token = searchParams.get("token"); // Token from query params
+  const { password } = await req.json(); // New password from request body
+
+  // Logic to reset the user's password
+
+  return Response.json({ message: "Password has been reset" });
+}
+```
+
+- `@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.
+
+### Step 3: Generate the OpenAPI Specification
+
+Run the following command to generate the OpenAPI schema based on your API routes:
+
+```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 `swagger.json` file in the `public` folder.
+
+### Step 4: View API Documentation
+
+With the `/api-docs` route generated from the init command, you can now access your API documentation through Swagger UI by navigating to `http://localhost:3000/api-docs`.
+
+## Configuration Options
+
+The `next.openapi.json` file allows you to configure the behavior of the OpenAPI generator, including options such as:
+
+- **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: `swagger`) OpenAPI UI interface.
+- **outputFile**: (default: `./swagger.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.
+
+## Interface providers
+
+<div align="center">
+<table>
+  <thead>
+   <th>SwaggerUI</th>
+   <th>Redoc</th>
+   <th>Stoplight Elements</th>
+   <th>RapiDoc</th>
+  </thead>
+  <tbody>
+   <tr>
+    <td>
+	<img width="320" alt="swagger" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/swagger.png" alt-text="swagger">
+	</td>
+	<td>
+	<img width="320" alt="redoc" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/redoc.png" alt-text="redoc">
+	</td>
+	<td>
+	<img width="320" alt="stoplight" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/stoplight.png" alt-text="stoplight">
+	</td>
+	<td>
+	<img width="320" alt="rapidoc" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/rapidoc.png" alt-text="rapidoc">
+	</td>
+   </tr>
+  </tbody>
+</table>

package/dist/lib/route-processor.js

@@ -89,7 +89,8 @@ export class RouteProcessor {
             ];
         }
         if (params) {
-            definition.parameters = params;
+            definition.parameters =
+                this.schemaProcessor.createRequestParamsSchema(params);
         }
         // Add request body
         if (MUTATION_HTTP_METHODS.includes(method.toUpperCase())) {
@@ -117,7 +118,7 @@ export class RouteProcessor {
             const aTags = Object.values(aMethods).flatMap((method) => method.tags || []);
             // Extract tags for all methods in path b
             const bTags = Object.values(bMethods).flatMap((method) => method.tags || []);
-            // Assume we are interested in only the first tags
+            // Let's user only the first tags
             const aPrimaryTag = aTags[0] || "";
             const bPrimaryTag = bTags[0] || "";
             // Sort alphabetically based on the first tag
@@ -128,7 +129,6 @@ export class RouteProcessor {
             // Compare lengths of the paths
             const aLength = a.split("/").length;
             const bLength = b.split("/").length;
-            // Return the result of length comparison
             return aLength - bLength; // Shorter paths come before longer ones
         }
         return Object.keys(paths)

package/dist/lib/schema-processor.js

@@ -5,111 +5,209 @@ import traverse from "@babel/traverse";
 import * as t from "@babel/types";
 export class SchemaProcessor {
     schemaDir;
+    typeDefinitions = {};
+    openapiDefinitions = {};
+    contentType = "";
     constructor(schemaDir) {
         this.schemaDir = path.resolve(schemaDir);
     }
-    findSchemaDefinition(schemaName) {
+    findSchemaDefinition(schemaName, contentType) {
         let schemaNode = null;
-        this.scanSchemaDir(this.schemaDir, schemaName, (node) => {
-            schemaNode = node;
-        });
+        // assign type that is actually processed
+        this.contentType = contentType;
+        this.scanSchemaDir(this.schemaDir, schemaName);
         return schemaNode;
     }
-    scanSchemaDir(dir, schemaName, callback) {
+    scanSchemaDir(dir, schemaName) {
         const files = fs.readdirSync(dir);
         files.forEach((file) => {
             const filePath = path.join(dir, file);
             const stat = fs.statSync(filePath);
             if (stat.isDirectory()) {
-                this.scanSchemaDir(filePath, schemaName, callback);
+                this.scanSchemaDir(filePath, schemaName);
             }
             else if (file.endsWith(".ts")) {
-                this.processSchemaFile(filePath, schemaName, callback);
+                this.processSchemaFile(filePath, schemaName);
             }
         });
     }
-    processSchemaFile(filePath, schemaName, callback) {
-        const content = fs.readFileSync(filePath, "utf-8");
-        const ast = parse(content, {
-            sourceType: "module",
-            plugins: ["typescript", "decorators-legacy"],
-        });
+    collectTypeDefinitions(ast, schemaName) {
         traverse.default(ast, {
             VariableDeclarator: (path) => {
                 if (t.isIdentifier(path.node.id, { name: schemaName })) {
-                    callback(path.node.init || path.node);
+                    const name = path.node.id.name;
+                    this.typeDefinitions[name] = path.node.init || path.node;
                 }
             },
             TSTypeAliasDeclaration: (path) => {
                 if (t.isIdentifier(path.node.id, { name: schemaName })) {
-                    callback(path.node.typeAnnotation);
+                    const name = path.node.id.name;
+                    this.typeDefinitions[name] = path.node.typeAnnotation;
                 }
             },
             TSInterfaceDeclaration: (path) => {
                 if (t.isIdentifier(path.node.id, { name: schemaName })) {
-                    callback(path.node);
+                    const name = path.node.id.name;
+                    this.typeDefinitions[name] = path.node;
+                }
+            },
+            TSEnumDeclaration: (path) => {
+                if (t.isIdentifier(path.node.id, { name: schemaName })) {
+                    const name = path.node.id.name;
+                    this.typeDefinitions[name] = path.node;
                 }
             },
         });
     }
-    extractTypesFromSchema(schema, dataType) {
-        const result = dataType === "params" ? [] : {};
-        const handleProperty = (property) => {
-            const key = property.key.name;
-            const typeAnnotation = property.typeAnnotation?.typeAnnotation?.type;
-            const type = this.getTypeFromAnnotation(typeAnnotation);
-            const isOptional = !!property.optional; // check if property is optional
-            let description = "";
-            // get comments for field
-            if (property.trailingComments && property.trailingComments.length) {
-                description = property.trailingComments[0].value.trim(); // get first comment
+    resolveType(typeName) {
+        const typeNode = this.typeDefinitions[typeName.toString()];
+        if (!typeNode)
+            return {};
+        if (t.isTSEnumDeclaration(typeNode)) {
+            const enumValues = this.processEnum(typeNode);
+            return enumValues;
+        }
+        if (t.isTSTypeLiteral(typeNode) || t.isTSInterfaceBody(typeNode)) {
+            const properties = {};
+            if ("members" in typeNode) {
+                (typeNode.members || []).forEach((member) => {
+                    if (t.isTSPropertySignature(member) && t.isIdentifier(member.key)) {
+                        const propName = member.key.name;
+                        const options = this.getPropertyOptions(member);
+                        const property = {
+                            ...this.resolveTSNodeType(member.typeAnnotation?.typeAnnotation),
+                            ...options,
+                        };
+                        properties[propName] = property;
+                    }
+                });
             }
-            const field = {
-                type: type,
-                description: description,
+            return { type: "object", properties };
+        }
+        if (t.isTSArrayType(typeNode)) {
+            return {
+                type: "array",
+                items: this.resolveTSNodeType(typeNode.elementType),
             };
-            if (dataType === "params") {
+        }
+        return {};
+    }
+    resolveTSNodeType(node) {
+        if (t.isTSStringKeyword(node))
+            return { type: "string" };
+        if (t.isTSNumberKeyword(node))
+            return { type: "number" };
+        if (t.isTSBooleanKeyword(node))
+            return { type: "boolean" };
+        if (t.isTSTypeReference(node) && t.isIdentifier(node.typeName)) {
+            const typeName = node.typeName.name;
+            // Find type definition
+            this.findSchemaDefinition(typeName, this.contentType);
+            return this.resolveType(node.typeName.name);
+        }
+        if (t.isTSArrayType(node)) {
+            return {
+                type: "array",
+                items: this.resolveTSNodeType(node.elementType),
+            };
+        }
+        if (t.isTSTypeLiteral(node)) {
+            const properties = {};
+            node.members.forEach((member) => {
+                if (t.isTSPropertySignature(member) && t.isIdentifier(member.key)) {
+                    const propName = member.key.name;
+                    properties[propName] = this.resolveTSNodeType(member.typeAnnotation?.typeAnnotation);
+                }
+            });
+            return { type: "object", properties };
+        }
+        return {};
+    }
+    processSchemaFile(filePath, schemaName) {
+        // Recognizes different elements of TS like variable, type, interface, enum
+        const content = fs.readFileSync(filePath, "utf-8");
+        const ast = parse(content, {
+            sourceType: "module",
+            plugins: ["typescript", "decorators-legacy"],
+        });
+        this.collectTypeDefinitions(ast, schemaName);
+        const definition = this.resolveType(schemaName);
+        this.openapiDefinitions[schemaName] = definition;
+        return definition;
+    }
+    processEnum(enumNode) {
+        // Initialization OpenAPI enum object
+        const enumSchema = {
+            type: "string",
+            enum: [],
+        };
+        // Iterate throught enum members
+        enumNode.members.forEach((member) => {
+            if (t.isTSEnumMember(member)) {
                 // @ts-ignore
-                result.push({
-                    name: key,
-                    in: "query",
-                    schema: field,
-                    required: !isOptional,
-                });
-            }
-            else {
-                result[key] = field;
+                const name = member.id?.name;
+                // @ts-ignore
+                const value = member.initializer?.value;
+                let type = member.initializer?.type;
+                if (type === "NumericLiteral") {
+                    enumSchema.type = "number";
+                }
+                const targetValue = value || name;
+                enumSchema.enum.push(targetValue);
             }
-        };
-        if (schema.body?.body) {
-            schema.body.body.forEach(handleProperty);
+        });
+        return enumSchema;
+    }
+    getPropertyOptions(node) {
+        const key = node.key.name;
+        const isOptional = !!node.optional; // check if property is optional
+        const typeName = node.typeAnnotation?.typeAnnotation?.typeName?.name;
+        let description = null;
+        // get comments for field
+        if (node.trailingComments && node.trailingComments.length) {
+            description = node.trailingComments[0].value.trim(); // get first comment
+        }
+        const options = {};
+        if (description) {
+            options.description = description;
+        }
+        if (this.contentType === "params") {
+            options.required = !isOptional;
         }
-        if (schema.type === "TSTypeLiteral" && schema.members) {
-            schema.members.forEach(handleProperty);
+        else if (this.contentType === "body") {
+            options.nullable = isOptional;
         }
-        return result;
+        return options;
     }
-    getTypeFromAnnotation(type) {
-        switch (type) {
-            case "TSStringKeyword":
-                return "string";
-            case "TSNumberKeyword":
-                return "number";
-            case "TSBooleanKeyword":
-                return "boolean";
-            // Add other cases as needed.
-            default:
-                return "object"; // fallback to object for unknown types
+    createRequestParamsSchema(params) {
+        const queryParams = [];
+        if (params.properties) {
+            for (let [name, value] of Object.entries(params.properties)) {
+                const param = {
+                    in: "query",
+                    name,
+                    schema: {
+                        type: value.type,
+                    },
+                    required: value.required,
+                };
+                if (value.enum) {
+                    param.schema.enum = value.enum;
+                }
+                if (value.description) {
+                    param.description = value.description;
+                    param.schema.description = value.description;
+                }
+                queryParams.push(param);
+            }
         }
+        return queryParams;
     }
     createRequestBodySchema(body) {
         return {
             content: {
                 "application/json": {
-                    schema: {
-                        type: "object",
-                        properties: body,
-                    },
+                    schema: body,
                 },
             },
         };
@@ -120,32 +218,19 @@ export class SchemaProcessor {
                 description: "Successful response",
                 content: {
                     "application/json": {
-                        schema: {
-                            type: "object",
-                            properties: responses,
-                        },
+                        schema: responses,
                     },
                 },
             },
         };
     }
     getSchemaContent({ paramsType, bodyType, responseType }) {
-        const paramsSchema = paramsType
-            ? this.findSchemaDefinition(paramsType)
-            : null;
-        const bodySchema = bodyType ? this.findSchemaDefinition(bodyType) : null;
-        const responseSchema = responseType
-            ? this.findSchemaDefinition(responseType)
-            : null;
-        let params = paramsSchema
-            ? this.extractTypesFromSchema(paramsSchema, "params")
-            : [];
-        let body = bodySchema
-            ? this.extractTypesFromSchema(bodySchema, "body")
-            : {};
-        let responses = responseSchema
-            ? this.extractTypesFromSchema(responseSchema, "responses")
-            : {};
+        this.findSchemaDefinition(paramsType, "params");
+        this.findSchemaDefinition(bodyType, "body");
+        this.findSchemaDefinition(responseType, "response");
+        const params = this.openapiDefinitions[paramsType];
+        const body = this.openapiDefinitions[bodyType];
+        const responses = this.openapiDefinitions[responseType];
         return {
             params,
             body,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.0.15",
+  "version": "0.0.18",
   "description": "Super fast and easy way to generate OpenAPI documentation automatically from API routes in a NextJS 14",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,8 @@
     "openapi",
     "swagger",
     "docs",
-    "api"
+    "api",
+    "redoc"
   ],
   "publishConfig": {
     "access": "public"