next-openapi-gen 0.0.8 → 0.0.10

package/README.md

@@ -1,16 +1,112 @@
-# Next OpenAPI Gen
+# next-openapi-gen
 
-**Next OpenAPI Gen** is a library that automatically generates an `openapi.json` specification for your Next.js project. This tool scans your API routes, schemas, and models, and generates a complete OpenAPI definition.
+**next-openapi-gen** super fast and easy way to generate OpenAPI 3.0 documentation automatically from API routes in a Next.js 14.
+
+## Prerequisites
+
+- Nextjs >= 14
+- Node >= 18
 
 ## Features
 
-- Auto-generates `next.openapi.json` in your project's root directory.
-- Scans API routes from `app/api/` and includes them in the generated OpenAPI specification.
-- Scans schemas from the `schemas/` directory and includes them in the OpenAPI components.
+- **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**:  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, Elements, or Redoc 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
 
-To install **Next OpenAPI Gen**, run:
+```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
+```
+
+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
-npm install next-openapi-gen --save-dev
+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.

package/dist/lib/route-processor.js

@@ -65,7 +65,7 @@ export class RouteProcessor {
         const routePath = this.getRoutePath(filePath);
         const rootPath = capitalize(routePath.split("/")[1]);
         const operationId = getOperationId(routePath, method);
-        const { summary, description, isOpenApi } = dataTypes;
+        const { summary, description, auth, isOpenApi } = dataTypes;
         if (this.config.includeOpenApiRoutes && !isOpenApi) {
             // If flag is enabled and there is no @openapi tag, then skip path
             return;
@@ -79,8 +79,18 @@ export class RouteProcessor {
             summary: summary,
             description: description,
             tags: [rootPath],
-            parameters: params,
         };
+        // Add auth
+        if (auth) {
+            definition.security = [
+                {
+                    [auth]: [],
+                },
+            ];
+        }
+        if (params) {
+            definition.parameters = params;
+        }
         // Add request body
         if (MUTATION_HTTP_METHODS.includes(method.toUpperCase())) {
             definition.requestBody =

package/dist/lib/utils.js

@@ -8,6 +8,7 @@ export function extractJSDocComments(path) {
     let paramsType = "";
     let bodyType = "";
     let responseType = "";
+    let auth = "";
     let isOpenApi = false;
     if (comments) {
         comments.forEach((comment) => {
@@ -17,6 +18,21 @@ export function extractJSDocComments(path) {
                 const summaryIndex = isOpenApi ? 1 : 0;
                 summary = commentValue.split("\n")[summaryIndex];
             }
+            if (commentValue.includes("@auth")) {
+                const regex = /@auth:\s*(.*)/;
+                const value = commentValue.match(regex)[1].trim();
+                switch (value) {
+                    case "bearer":
+                        auth = "BearerAuth";
+                        break;
+                    case "basic":
+                        auth = "BasicAuth";
+                        break;
+                    case "apikey":
+                        auth = "ApiKeyAuth";
+                        break;
+                }
+            }
             if (commentValue.includes("@desc")) {
                 const regex = /@desc:\s*(.*)/;
                 description = commentValue.match(regex)[1].trim();
@@ -33,6 +49,7 @@ export function extractJSDocComments(path) {
         });
     }
     return {
+        auth,
         summary,
         description,
         paramsType,

package/dist/openapi-template.js

@@ -11,6 +11,15 @@ export default {
             description: "Local development server",
         },
     ],
+    components: {
+        securitySchemes: {
+            BearerAuth: {
+                type: "http",
+                scheme: "bearer",
+                bearerFormat: "JWT",
+            },
+        },
+    },
     apiDir: "./src/app/api",
     schemaDir: "./src",
     docsUrl: "api-docs",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.0.8",
-  "description": "Automatically generate OpenAPI documentation for Next.js API",
+  "version": "0.0.10",
+  "description": "Super fast and easy way to generate OpenAPI 3.0 documentation automatically from API routes in a NextJS 14.",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.mjs",