next-openapi-gen 0.0.18 → 0.1.0

package/README.md

@@ -1,15 +1,13 @@
 # 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!
+**next-openapi-gen** super fast and easy way to generate OpenAPI 3.0 documentation automatically from API routes in NextJS.
 
 ## Prerequisites
 
-- Nextjs >= 14
+- Next.js >= 14
 - Node >= 18
 
-## Supported interfaces
+## Interfaces
 
 - Swagger
 - Redoc
@@ -18,15 +16,13 @@ With support for multiple user interfaces next-openapi-gen makes documenting you
 
 ## 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.
+- **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 `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
@@ -57,49 +53,103 @@ This command does the following:
 
 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.
+<div align="center">
+  <table>
+    <tr>
+      <th>Login route</th>
+      <th>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" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-login.png" alt-text="api-login"/>
+  </td>
+  </tr>
+
+  <tr>
+      <th>Users route</th>
+      <th>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" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-users.png" alt-text="api-users"/>
+  </td>
+  </tr>
+</table>
+</div>
 
 ### Step 3: Generate the OpenAPI Specification
 
@@ -115,6 +165,15 @@ This command processes all your API routes, extracts the necessary information f
 
 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`.
 
+## JSDoc tags
+
+- `@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.
+
 ## Configuration Options
 
 The `next.openapi.json` file allows you to configure the behavior of the OpenAPI generator, including options such as:

package/dist/components/swagger.js

@@ -1,21 +1,21 @@
-export const swaggerDeps = ["swagger-ui"];
+export const swaggerDeps = ["swagger-ui", "swagger-ui-react"];
 export function SwaggerUI(outputFile) {
-    return `
-import "swagger-ui-react/swagger-ui.css";
-
-import dynamic from "next/dynamic";
-
-const SwaggerUI = dynamic(() => import("swagger-ui-react"), {
-  ssr: false,
-  loading: () => <p>Loading Component...</p>,
-});
-
-export default async function ApiDocsPage() {
-  return (
-    <section>
-      <SwaggerUI url="/${outputFile}" />
-    </section>
-  );
-}
+    return `
+import "swagger-ui-react/swagger-ui.css";
+
+import dynamic from "next/dynamic";
+
+const SwaggerUI = dynamic(() => import("swagger-ui-react"), {
+  ssr: false,
+  loading: () => <p>Loading Component...</p>,
+});
+
+export default async function ApiDocsPage() {
+  return (
+    <section>
+      <SwaggerUI url="/${outputFile}" />
+    </section>
+  );
+}
 `;
 }

package/dist/lib/schema-processor.js

@@ -121,6 +121,16 @@ export class SchemaProcessor {
             });
             return { type: "object", properties };
         }
+        if (t.isTSUnionType(node)) {
+            return {
+                anyOf: node.types.map((subNode) => this.resolveTSNodeType(subNode)),
+            };
+        }
+        // case where a type is a reference to another defined type
+        if (t.isTSTypeReference(node) && t.isIdentifier(node.typeName)) {
+            return { $ref: `#/components/schemas/${node.typeName.name}` };
+        }
+        console.warn("Unrecognized TypeScript type node:", node);
         return {};
     }
     processSchemaFile(filePath, schemaName) {

package/package.json

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