next-openapi-gen 0.2.2 → 0.3.1

package/README.md

@@ -9,7 +9,7 @@
 
 ## Interfaces
 
-- Scalar
+- Scalar 🆕
 - Swagger
 - Redoc
 - Stoplight Elements
@@ -89,6 +89,7 @@ Annotate your API routes using JSDoc comments. Here's an example:
   </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>
@@ -148,6 +149,7 @@ Annotate your API routes using JSDoc comments. Here's an example:
   </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>
@@ -201,6 +203,9 @@ The `next.openapi.json` file allows you to configure the behavior of the OpenAPI
   </thead>
   <tbody>
    <tr>
+   <td>
+	<img width="320" alt="scalar" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/scalar.png" alt-text="scalar">
+	</td>
     <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>

package/dist/lib/route-processor.js

@@ -4,7 +4,7 @@ import path from "path";
 import traverse from "@babel/traverse";
 import { parse } from "@babel/parser";
 import { SchemaProcessor } from "./schema-processor.js";
-import { capitalize, extractJSDocComments, getOperationId } from "./utils.js";
+import { capitalize, extractJSDocComments, extractPathParameters, getOperationId, } from "./utils.js";
 const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 const MUTATION_HTTP_METHODS = ["PATCH", "POST", "PUT"];
 export class RouteProcessor {
@@ -38,7 +38,8 @@ export class RouteProcessor {
                     const dataTypes = extractJSDocComments(path);
                     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))
+                        if (!this.config.includeOpenApiRoutes ||
+                            (this.config.includeOpenApiRoutes && dataTypes.isOpenApi))
                             this.addRouteToPaths(declaration.id.name, filePath, dataTypes);
                     }
                 }
@@ -48,7 +49,8 @@ export class RouteProcessor {
                             if (this.isRoute(decl.id.name)) {
                                 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))
+                                if (!this.config.includeOpenApiRoutes ||
+                                    (this.config.includeOpenApiRoutes && dataTypes.isOpenApi))
                                     this.addRouteToPaths(decl.id.name, filePath, dataTypes);
                             }
                         }
@@ -75,8 +77,10 @@ export class RouteProcessor {
                 this.scanApiRoutes(filePath);
                 // @ts-ignore
             }
-            else if (file.endsWith(".ts")) {
-                this.processFile(filePath);
+            else if (file.endsWith(".ts") || file.endsWith(".tsx")) {
+                if (file === "route.ts" || file === "route.tsx") {
+                    this.processFile(filePath);
+                }
             }
         });
     }
@@ -113,7 +117,21 @@ export class RouteProcessor {
             definition.parameters =
                 this.schemaProcessor.createRequestParamsSchema(params);
         }
-        if (pathParams) {
+        // Add path parameters
+        const pathParamNames = extractPathParameters(routePath);
+        if (pathParamNames.length > 0) {
+            // If we have path parameters but no schema, create a default schema
+            if (!pathParams) {
+                const defaultPathParams = this.schemaProcessor.createDefaultPathParamsSchema(pathParamNames);
+                definition.parameters.push(...defaultPathParams);
+            }
+            else {
+                const moreParams = this.schemaProcessor.createRequestParamsSchema(pathParams, true);
+                definition.parameters.push(...moreParams);
+            }
+        }
+        else if (pathParams) {
+            // If no path parameters in route but we have a schema, use it
             const moreParams = this.schemaProcessor.createRequestParamsSchema(pathParams, true);
             definition.parameters.push(...moreParams);
         }
@@ -129,14 +147,29 @@ export class RouteProcessor {
         this.swaggerPaths[routePath][method] = definition;
     }
     getRoutePath(filePath) {
+        // First, check if it's an app router path
+        if (filePath.includes("/app/api/")) {
+            // Get the relative path from the api directory
+            const apiDirPos = filePath.indexOf("/app/api/");
+            let relativePath = filePath.substring(apiDirPos + "/app/api".length);
+            // Remove the /route.ts or /route.tsx suffix
+            relativePath = relativePath.replace(/\/route\.tsx?$/, "");
+            // Convert directory separators to URL path format
+            relativePath = relativePath.replaceAll("\\", "/");
+            // Convert Next.js dynamic route syntax to OpenAPI parameter syntax
+            relativePath = relativePath.replace(/\/\[([^\]]+)\]/g, "/{$1}");
+            // Handle catch-all routes ([...param])
+            relativePath = relativePath.replace(/\/\[\.\.\.(.*)\]/g, "/{$1}");
+            return relativePath;
+        }
+        // For pages router or other formats
         const suffixPath = filePath.split("api")[1];
         return suffixPath
-            .replace("route.ts", "")
+            .replace(/route\.tsx?$/, "")
             .replaceAll("\\", "/")
             .replace(/\/$/, "")
-            // Turns NextJS-style dynamic routes into OpenAPI-style dynamic routes
-            .replaceAll("[", "{")
-            .replaceAll("]", "}");
+            .replace(/\/\[([^\]]+)\]/g, "/{$1}") // Replace [param] with {param}
+            .replace(/\/\[\.\.\.(.*)\]/g, "/{$1}"); // Replace [...param] with {param}
     }
     getSortedPaths(paths) {
         function comparePaths(a, b) {

package/dist/lib/schema-processor.js

@@ -111,7 +111,7 @@ export class SchemaProcessor {
         return false;
     }
     isDateObject(node) {
-        return t.isNewExpression(node) && t.isIdentifier(node.callee, { name: "Date" });
+        return (t.isNewExpression(node) && t.isIdentifier(node.callee, { name: "Date" }));
     }
     isDateNode(node) {
         return this.isDateString(node) || this.isDateObject(node);
@@ -199,9 +199,7 @@ export class SchemaProcessor {
         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) {
@@ -219,6 +217,71 @@ export class SchemaProcessor {
         }
         return options;
     }
+    /**
+     * Generate example values based on parameter type and name
+     */
+    getExampleForParam(paramName, type = "string") {
+        // Common ID-like parameters
+        if (paramName === "id" ||
+            paramName.endsWith("Id") ||
+            paramName.endsWith("_id")) {
+            return type === "string" ? "123abc" : 123;
+        }
+        // For specific common parameter names
+        switch (paramName.toLowerCase()) {
+            case "slug":
+                return "example-slug";
+            case "uuid":
+                return "123e4567-e89b-12d3-a456-426614174000";
+            case "username":
+                return "johndoe";
+            case "email":
+                return "user@example.com";
+            case "name":
+                return "example-name";
+            case "date":
+                return "2023-01-01";
+            case "page":
+                return 1;
+            default:
+                // Default examples by type
+                if (type === "string")
+                    return "example";
+                if (type === "number")
+                    return 1;
+                if (type === "boolean")
+                    return true;
+                return "example";
+        }
+    }
+    /**
+     * Create a default schema for path parameters when no schema is defined
+     */
+    createDefaultPathParamsSchema(paramNames) {
+        return paramNames.map((paramName) => {
+            // Guess the parameter type based on the name
+            let type = "string";
+            if (paramName === "id" ||
+                paramName.endsWith("Id") ||
+                paramName === "page" ||
+                paramName === "limit" ||
+                paramName === "size" ||
+                paramName === "count") {
+                type = "number";
+            }
+            const example = this.getExampleForParam(paramName, type);
+            return {
+                name: paramName,
+                in: "path",
+                required: true,
+                schema: {
+                    type: type,
+                },
+                example: example,
+                description: `Path parameter: ${paramName}`,
+            };
+        });
+    }
     createRequestParamsSchema(params, isPathParam = false) {
         const queryParams = [];
         if (params.properties) {
@@ -229,7 +292,7 @@ export class SchemaProcessor {
                     schema: {
                         type: value.type,
                     },
-                    required: value.required,
+                    required: isPathParam ? true : value.required, // Path parameters are always required
                 };
                 if (value.enum) {
                     param.schema.enum = value.enum;
@@ -238,6 +301,11 @@ export class SchemaProcessor {
                     param.description = value.description;
                     param.schema.description = value.description;
                 }
+                // Add examples for path parameters
+                if (isPathParam) {
+                    const example = this.getExampleForParam(name, value.type);
+                    param.example = example;
+                }
                 queryParams.push(param);
             }
         }
@@ -264,7 +332,7 @@ export class SchemaProcessor {
             },
         };
     }
-    getSchemaContent({ paramsType, pathParamsType, bodyType, responseType }) {
+    getSchemaContent({ paramsType, pathParamsType, bodyType, responseType, }) {
         let params = this.openapiDefinitions[paramsType];
         let pathParams = this.openapiDefinitions[pathParamsType];
         let body = this.openapiDefinitions[bodyType];

package/dist/lib/utils.js

@@ -1,6 +1,19 @@
 export function capitalize(string) {
     return string.charAt(0).toUpperCase() + string.slice(1);
 }
+/**
+ * Extract path parameters from a route path
+ * e.g. /users/{id}/posts/{postId} -> ['id', 'postId']
+ */
+export function extractPathParameters(routePath) {
+    const paramRegex = /{([^}]+)}/g;
+    const params = [];
+    let match;
+    while ((match = paramRegex.exec(routePath)) !== null) {
+        params.push(match[1]);
+    }
+    return params;
+}
 export function extractJSDocComments(path) {
     const comments = path.node.leadingComments;
     let summary = "";
@@ -80,6 +93,35 @@ export function cleanSpec(spec) {
     ];
     const newSpec = { ...spec };
     propsToRemove.forEach((key) => delete newSpec[key]);
+    // Process paths to ensure good examples for path parameters
+    if (newSpec.paths) {
+        Object.keys(newSpec.paths).forEach((path) => {
+            // Check if path contains parameters
+            if (path.includes("{") && path.includes("}")) {
+                // For each HTTP method in this path
+                Object.keys(newSpec.paths[path]).forEach((method) => {
+                    const operation = newSpec.paths[path][method];
+                    // Set example properties for each path parameter
+                    if (operation.parameters) {
+                        operation.parameters.forEach((param) => {
+                            if (param.in === "path" && !param.example) {
+                                // Generate an example based on parameter name
+                                if (param.name === "id" || param.name.endsWith("Id")) {
+                                    param.example = 123;
+                                }
+                                else if (param.name === "slug") {
+                                    param.example = "example-slug";
+                                }
+                                else {
+                                    param.example = "example";
+                                }
+                            }
+                        });
+                    }
+                });
+            }
+        });
+    }
     return newSpec;
 }
 export function getOperationId(routePath, method) {

package/package.json

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