next-openapi-gen 0.2.2 → 0.3.2

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

@@ -11,6 +11,7 @@ export class SchemaProcessor {
     directoryCache = {};
     statCache = {};
     processSchemaTracker = {};
+    processingTypes = new Set();
     constructor(schemaDir) {
         this.schemaDir = path.resolve(schemaDir);
     }
@@ -71,37 +72,49 @@ export class SchemaProcessor {
         });
     }
     resolveType(typeName) {
-        const typeNode = this.typeDefinitions[typeName.toString()];
-        if (!typeNode)
-            return {};
-        if (t.isTSEnumDeclaration(typeNode)) {
-            const enumValues = this.processEnum(typeNode);
-            return enumValues;
+        if (this.processingTypes.has(typeName)) {
+            // Return reference to type to avoid infinite recursion
+            return { $ref: `#/components/schemas/${typeName}` };
         }
-        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;
-                    }
-                });
+        // Add type to precessing types
+        this.processingTypes.add(typeName);
+        try {
+            const typeNode = this.typeDefinitions[typeName.toString()];
+            if (!typeNode)
+                return {};
+            if (t.isTSEnumDeclaration(typeNode)) {
+                const enumValues = this.processEnum(typeNode);
+                return enumValues;
             }
-            return { type: "object", properties };
+            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;
+                        }
+                    });
+                }
+                return { type: "object", properties };
+            }
+            if (t.isTSArrayType(typeNode)) {
+                return {
+                    type: "array",
+                    items: this.resolveTSNodeType(typeNode.elementType),
+                };
+            }
+            return {};
         }
-        if (t.isTSArrayType(typeNode)) {
-            return {
-                type: "array",
-                items: this.resolveTSNodeType(typeNode.elementType),
-            };
+        finally {
+            // Remove type from processed set after we finish
+            this.processingTypes.delete(typeName);
         }
-        return {};
     }
     isDateString(node) {
         if (t.isStringLiteral(node)) {
@@ -111,22 +124,91 @@ 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);
     }
     resolveTSNodeType(node) {
+        if (!node)
+            return { type: "object" }; // Default type for undefined/null
         if (t.isTSStringKeyword(node))
             return { type: "string" };
         if (t.isTSNumberKeyword(node))
             return { type: "number" };
         if (t.isTSBooleanKeyword(node))
             return { type: "boolean" };
+        if (t.isTSAnyKeyword(node) || t.isTSUnknownKeyword(node))
+            return { type: "object" };
+        if (t.isTSVoidKeyword(node) ||
+            t.isTSNullKeyword(node) ||
+            t.isTSUndefinedKeyword(node))
+            return { type: "null" };
         if (this.isDateNode(node))
-            return { type: "Date" };
+            return { type: "string", format: "date-time" };
+        // Handle literal types like "admin" | "member" | "guest"
+        if (t.isTSLiteralType(node)) {
+            if (t.isStringLiteral(node.literal)) {
+                return {
+                    type: "string",
+                    enum: [node.literal.value],
+                };
+            }
+            else if (t.isNumericLiteral(node.literal)) {
+                return {
+                    type: "number",
+                    enum: [node.literal.value],
+                };
+            }
+            else if (t.isBooleanLiteral(node.literal)) {
+                return {
+                    type: "boolean",
+                    enum: [node.literal.value],
+                };
+            }
+        }
         if (t.isTSTypeReference(node) && t.isIdentifier(node.typeName)) {
             const typeName = node.typeName.name;
+            // Special handling for built-in types
+            if (typeName === "Date") {
+                return { type: "string", format: "date-time" };
+            }
+            if (typeName === "Array" || typeName === "ReadonlyArray") {
+                if (node.typeParameters && node.typeParameters.params.length > 0) {
+                    return {
+                        type: "array",
+                        items: this.resolveTSNodeType(node.typeParameters.params[0]),
+                    };
+                }
+                return { type: "array", items: { type: "object" } };
+            }
+            if (typeName === "Record") {
+                if (node.typeParameters && node.typeParameters.params.length > 1) {
+                    const keyType = this.resolveTSNodeType(node.typeParameters.params[0]);
+                    const valueType = this.resolveTSNodeType(node.typeParameters.params[1]);
+                    return {
+                        type: "object",
+                        additionalProperties: valueType,
+                    };
+                }
+                return { type: "object", additionalProperties: true };
+            }
+            if (typeName === "Partial" ||
+                typeName === "Required" ||
+                typeName === "Readonly") {
+                if (node.typeParameters && node.typeParameters.params.length > 0) {
+                    return this.resolveTSNodeType(node.typeParameters.params[0]);
+                }
+            }
+            if (typeName === "Pick" || typeName === "Omit") {
+                if (node.typeParameters && node.typeParameters.params.length > 0) {
+                    return this.resolveTSNodeType(node.typeParameters.params[0]);
+                }
+            }
+            // Check if it is a type that we are already processing
+            if (this.processingTypes.has(typeName)) {
+                return { $ref: `#/components/schemas/${typeName}` };
+            }
             // Find type definition
             this.findSchemaDefinition(typeName, this.contentType);
             return this.resolveType(node.typeName.name);
@@ -148,32 +230,115 @@ export class SchemaProcessor {
             return { type: "object", properties };
         }
         if (t.isTSUnionType(node)) {
+            // Handle union types with literal types, like "admin" | "member" | "guest"
+            const literals = node.types.filter((type) => t.isTSLiteralType(type));
+            // Check if all union elements are literals
+            if (literals.length === node.types.length) {
+                // All union members are literals, convert to enum
+                const enumValues = literals
+                    .map((type) => {
+                    if (t.isTSLiteralType(type) && t.isStringLiteral(type.literal)) {
+                        return type.literal.value;
+                    }
+                    else if (t.isTSLiteralType(type) &&
+                        t.isNumericLiteral(type.literal)) {
+                        return type.literal.value;
+                    }
+                    else if (t.isTSLiteralType(type) &&
+                        t.isBooleanLiteral(type.literal)) {
+                        return type.literal.value;
+                    }
+                    return null;
+                })
+                    .filter((value) => value !== null);
+                if (enumValues.length > 0) {
+                    // Check if all enum values are of the same type
+                    const firstType = typeof enumValues[0];
+                    const sameType = enumValues.every((val) => typeof val === firstType);
+                    if (sameType) {
+                        return {
+                            type: firstType,
+                            enum: enumValues,
+                        };
+                    }
+                }
+            }
+            // Handling null | undefined in type union
+            const nullableTypes = node.types.filter((type) => t.isTSNullKeyword(type) ||
+                t.isTSUndefinedKeyword(type) ||
+                t.isTSVoidKeyword(type));
+            const nonNullableTypes = node.types.filter((type) => !t.isTSNullKeyword(type) &&
+                !t.isTSUndefinedKeyword(type) &&
+                !t.isTSVoidKeyword(type));
+            // If a type can be null/undefined, we mark it as nullable
+            if (nullableTypes.length > 0 && nonNullableTypes.length === 1) {
+                const mainType = this.resolveTSNodeType(nonNullableTypes[0]);
+                return {
+                    ...mainType,
+                    nullable: true,
+                };
+            }
+            // Standard union type support via oneOf
+            return {
+                oneOf: node.types
+                    .filter((type) => !t.isTSNullKeyword(type) &&
+                    !t.isTSUndefinedKeyword(type) &&
+                    !t.isTSVoidKeyword(type))
+                    .map((subNode) => this.resolveTSNodeType(subNode)),
+            };
+        }
+        if (t.isTSIntersectionType(node)) {
+            // For intersection types, we combine properties
+            const allProperties = {};
+            const requiredProperties = [];
+            node.types.forEach((typeNode) => {
+                const resolvedType = this.resolveTSNodeType(typeNode);
+                if (resolvedType.type === "object" && resolvedType.properties) {
+                    Object.entries(resolvedType.properties).forEach(([key, value]) => {
+                        allProperties[key] = value;
+                        // @ts-ignore
+                        if (value.required) {
+                            requiredProperties.push(key);
+                        }
+                    });
+                }
+            });
             return {
-                anyOf: node.types.map((subNode) => this.resolveTSNodeType(subNode)),
+                type: "object",
+                properties: allProperties,
+                required: requiredProperties.length > 0 ? requiredProperties : undefined,
             };
         }
-        // case where a type is a reference to another defined type
+        // 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 {};
+        return { type: "object" }; // By default we return an object
     }
     processSchemaFile(filePath, schemaName) {
         // Check if the file has already been processed
         if (this.processSchemaTracker[`${filePath}-${schemaName}`])
             return;
-        // 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;
-        this.processSchemaTracker[`${filePath}-${schemaName}`] = true;
-        return definition;
+        try {
+            // 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);
+            // Reset the set of processed types before each schema processing
+            this.processingTypes.clear();
+            const definition = this.resolveType(schemaName);
+            this.openapiDefinitions[schemaName] = definition;
+            this.processSchemaTracker[`${filePath}-${schemaName}`] = true;
+            return definition;
+        }
+        catch (error) {
+            console.error(`Error processing schema file ${filePath} for schema ${schemaName}:`, error);
+            return { type: "object" }; // By default we return an empty object on error
+        }
     }
     processEnum(enumNode) {
         // Initialization OpenAPI enum object
@@ -199,9 +364,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 +382,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 +457,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 +466,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 +497,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 = "";
@@ -16,8 +29,7 @@ export function extractJSDocComments(path) {
             const commentValue = cleanComment(comment.value);
             isOpenApi = commentValue.includes("@openapi");
             if (!summary) {
-                const summaryIndex = isOpenApi ? 1 : 0;
-                summary = commentValue.split("\n")[summaryIndex];
+                summary = commentValue.split("\n")[0];
             }
             if (commentValue.includes("@auth")) {
                 const regex = /@auth:\s*(.*)/;
@@ -64,7 +76,7 @@ export function extractJSDocComments(path) {
     };
 }
 export function extractTypeFromComment(commentValue, tag) {
-    return commentValue.match(new RegExp(`${tag}\\s*:\\s*(\\w+)`))?.[1] || "";
+    return commentValue.match(new RegExp(`${tag}\\s*\\s*(\\w+)`))?.[1] || "";
 }
 export function cleanComment(commentValue) {
     return commentValue.replace(/\*\s*/g, "").trim();
@@ -80,6 +92,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.2",
   "description": "Super fast and easy way to generate OpenAPI documentation automatically from API routes in NextJS.",
   "type": "module",
   "main": "dist/index.js",