next-openapi-gen 0.6.0 → 0.6.2

package/README.md

@@ -154,6 +154,7 @@ export async function GET(
 | `@bodyDescription`     | Request body description                                                            |
 | `@response`            | Response type/schema                                                                |
 | `@responseDescription` | Response description                                                                |
+| `@contentType`         | Request body content type (`application/json`, `multipart/form-data`)               |
 | `@auth`                | Authorization type (`bearer`, `basic`, `apikey`)                                    |
 | `@tag`                 | Custom tag                                                                          |
 | `@deprecated`          | Marks the route as deprecated                                                       |
@@ -344,6 +345,34 @@ export async function GET() {
 }
 ```
 
+### File Uploads / Multipart Form Data
+
+```typescript
+// src/app/api/upload/route.ts
+
+// TypeScript
+type FileUploadFormData = {
+  file: File;
+  description?: string;
+  category: string;
+};
+
+// Or Zod
+const FileUploadSchema = z.object({
+  file: z.custom<File>().describe("Image file (PNG/JPG)"),
+  description: z.string().optional().describe("File description"),
+  category: z.string().describe("File category"),
+});
+
+/**
+ * @body FileUploadSchema
+ * @contentType multipart/form-data
+ */
+export async function POST() {
+  // ...
+}
+```
+
 ## Advanced Usage
 
 ### Automatic Path Parameter Detection

package/dist/lib/route-processor.js

@@ -160,7 +160,7 @@ export class RouteProcessor {
         }
         // Add request body
         if (MUTATION_HTTP_METHODS.includes(method.toUpperCase())) {
-            definition.requestBody = this.schemaProcessor.createRequestBodySchema(body, bodyDescription);
+            definition.requestBody = this.schemaProcessor.createRequestBodySchema(body, bodyDescription, dataTypes.contentType);
         }
         // Add responses
         definition.responses = responses

package/dist/lib/schema-processor.js

@@ -188,6 +188,9 @@ export class SchemaProcessor {
                     items: this.resolveTSNodeType(typeNode.elementType),
                 };
             }
+            if (t.isTSUnionType(typeNode)) {
+                return this.resolveTSNodeType(typeNode);
+            }
             return {};
         }
         finally {
@@ -498,6 +501,44 @@ export class SchemaProcessor {
                 return "example";
         }
     }
+    detectContentType(bodyType, explicitContentType) {
+        if (explicitContentType) {
+            return explicitContentType;
+        }
+        // Automatic detection based on type name
+        if (bodyType &&
+            (bodyType.toLowerCase().includes("formdata") ||
+                bodyType.toLowerCase().includes("fileupload") ||
+                bodyType.toLowerCase().includes("multipart"))) {
+            return "multipart/form-data";
+        }
+        return "application/json";
+    }
+    createFormDataSchema(body) {
+        if (!body.properties) {
+            return body;
+        }
+        const formDataProperties = {};
+        Object.entries(body.properties).forEach(([key, value]) => {
+            // Convert File types to binary format
+            if (value.type === "object" &&
+                (key.toLowerCase().includes("file") ||
+                    value.description?.toLowerCase().includes("file"))) {
+                formDataProperties[key] = {
+                    type: "string",
+                    format: "binary",
+                    description: value.description,
+                };
+            }
+            else {
+                formDataProperties[key] = value;
+            }
+        });
+        return {
+            ...body,
+            properties: formDataProperties,
+        };
+    }
     /**
      * Create a default schema for path parameters when no schema is defined
      */
@@ -555,18 +596,24 @@ export class SchemaProcessor {
         }
         return queryParams;
     }
-    createRequestBodySchema(body, description) {
-        const schema = {
+    createRequestBodySchema(body, description, contentType) {
+        const detectedContentType = this.detectContentType(body?.type || "", contentType);
+        let schema = body;
+        // If it is multipart/form-data, convert schema
+        if (detectedContentType === "multipart/form-data") {
+            schema = this.createFormDataSchema(body);
+        }
+        const requestBody = {
             content: {
-                "application/json": {
-                    schema: body,
+                [detectedContentType]: {
+                    schema: schema,
                 },
             },
         };
         if (description) {
-            schema.description = description;
+            requestBody.description = description;
         }
-        return schema;
+        return requestBody;
     }
     createResponseSchema(responses, description) {
         return {

package/dist/lib/utils.js

@@ -28,6 +28,7 @@ export function extractJSDocComments(path) {
     let deprecated = false;
     let bodyDescription = "";
     let responseDescription = "";
+    let contentType = "";
     if (comments) {
         comments.forEach((comment) => {
             const commentValue = cleanComment(comment.value);
@@ -90,6 +91,13 @@ export function extractJSDocComments(path) {
             if (commentValue.includes("@response")) {
                 responseType = extractTypeFromComment(commentValue, "@response");
             }
+            if (commentValue.includes("@contentType")) {
+                const regex = /@contentType\s*(.*)/;
+                const match = commentValue.match(regex);
+                if (match && match[1]) {
+                    contentType = match[1].trim();
+                }
+            }
         });
     }
     return {
@@ -105,6 +113,7 @@ export function extractJSDocComments(path) {
         deprecated,
         bodyDescription,
         responseDescription,
+        contentType,
     };
 }
 export function extractTypeFromComment(commentValue, tag) {

package/dist/lib/zod-converter.js

@@ -846,6 +846,22 @@ export class ZodSchemaConverter {
             !t.isIdentifier(node.callee.property)) {
             return { type: "string" };
         }
+        if (t.isMemberExpression(node.callee) &&
+            t.isIdentifier(node.callee.property)) {
+            const zodType = node.callee.property.name;
+            // Custom() support for FormData
+            if (zodType === "custom" && node.arguments.length > 0) {
+                // Check if it is FormData
+                if (t.isArrowFunctionExpression(node.arguments[0])) {
+                    // Assume custom FormData validation
+                    return {
+                        type: "object",
+                        additionalProperties: true,
+                        description: "Form data object",
+                    };
+                }
+            }
+        }
         const zodType = node.callee.property.name;
         let schema = {};
         // Basic type mapping

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Automatically generate OpenAPI 3.0 documentation from Next.js projects, with support for TypeScript types and Zod schemas.",
   "type": "module",
   "main": "dist/index.js",