next-openapi-gen 0.6.1 → 0.6.4

package/README.md

@@ -75,6 +75,9 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
 | `outputFile`           | Path to the OpenAPI output file                  |
 | `docsUrl`              | API documentation URL (for Swagger UI)           |
 | `includeOpenApiRoutes` | Whether to include only routes with @openapi tag |
+| `defaultResponseSet`   | Default error response set for all endpoints     |
+| `responseSets`         | Named sets of error response codes               |
+| `errorConfig`          | Error schema configuration                       |
 
 ## Documenting Your API
 
@@ -154,6 +157,9 @@ export async function GET(
 | `@bodyDescription`     | Request body description                                                            |
 | `@response`            | Response type/schema                                                                |
 | `@responseDescription` | Response description                                                                |
+| `@responseSet`         | Override default response set (`public`, `auth`, `none`)                            |
+| `@add`                 | Add custom response codes (`409:ConflictResponse`, `429`)                           |
+| `@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 +350,117 @@ 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() {
+  // ...
+}
+```
+
+## Response Management
+
+### Zero Config + Response Sets
+
+Configure reusable error sets in `next.openapi.json`:
+
+```json
+{
+  "defaultResponseSet": "common",
+  "responseSets": {
+    "common": ["400", "401", "500"],
+    "public": ["400", "500"],
+    "auth": ["400", "401", "403", "500"]
+  }
+}
+```
+
+### Usage Examples
+
+```typescript
+/**
+ * Auto-default responses
+ * @response UserResponse
+ * @openapi
+ */
+export async function GET() {}
+// Generates: 200:UserResponse + common errors (400, 401, 500)
+
+/**
+ * Override response set
+ * @response ProductResponse
+ * @responseSet public
+ * @openapi
+ */
+export async function GET() {}
+// Generates: 200:ProductResponse + public errors (400, 500)
+
+/**
+ * Add custom responses
+ * @response 201:UserResponse
+ * @add 409:ConflictResponse
+ * @openapi
+ */
+export async function POST() {}
+// Generates: 201:UserResponse + common errors + 409:ConflictResponse
+
+/**
+ * Combine multiple sets
+ * @response UserResponse
+ * @responseSet auth,crud
+ * @add 429:RateLimitResponse
+ * @openapi
+ */
+export async function PUT() {}
+// Combines: auth + crud errors + custom 429
+```
+
+### Error Schema Configuration
+
+#### Define consistent error schemas using templates:
+
+```json
+{
+  "errorConfig": {
+    "template": {
+      "type": "object",
+      "properties": {
+        "error": {
+          "type": "string",
+          "example": "{{ERROR_MESSAGE}}"
+        }
+      }
+    },
+    "codes": {
+      "invalid_request": {
+        "description": "Invalid request",
+        "variables": { "ERROR_MESSAGE": "Validation failed" }
+      }
+    }
+  }
+}
+```
+
 ## Advanced Usage
 
 ### Automatic Path Parameter Detection

package/dist/lib/openapi-generator.js

@@ -14,7 +14,7 @@ export class OpenApiGenerator {
     }
     getConfig() {
         // @ts-ignore
-        const { apiDir, schemaDir, docsUrl, ui, outputFile, includeOpenApiRoutes, schemaType = "typescript" } = this.template;
+        const { apiDir, schemaDir, docsUrl, ui, outputFile, includeOpenApiRoutes, schemaType = "typescript", defaultResponseSet, responseSets, errorConfig } = this.template;
         return {
             apiDir,
             schemaDir,
@@ -23,6 +23,9 @@ export class OpenApiGenerator {
             outputFile,
             includeOpenApiRoutes,
             schemaType,
+            defaultResponseSet,
+            responseSets,
+            errorConfig,
         };
     }
     generate() {
@@ -57,6 +60,21 @@ export class OpenApiGenerator {
         if (!this.template.components.schemas) {
             this.template.components.schemas = {};
         }
+        // Generate error responses using errorConfig or manual definitions
+        if (!this.template.components.responses) {
+            this.template.components.responses = {};
+        }
+        const errorConfig = this.config.errorConfig;
+        if (errorConfig) {
+            this.generateErrorResponsesFromConfig(errorConfig);
+        }
+        else if (this.config.errorDefinitions) {
+            // Use manual definitions (existing logic - if exists)
+            Object.entries(this.config.errorDefinitions).forEach(([code, errorDef]) => {
+                this.template.components.responses[code] =
+                    this.createErrorResponseComponent(code, errorDef);
+            });
+        }
         // Get defined schemas from the processor
         const definedSchemas = this.routeProcessor
             .getSchemaProcessor()
@@ -70,4 +88,70 @@ export class OpenApiGenerator {
         const openapiSpec = cleanSpec(this.template);
         return openapiSpec;
     }
+    generateErrorResponsesFromConfig(errorConfig) {
+        const { template, codes, variables: globalVars = {} } = errorConfig;
+        Object.entries(codes).forEach(([errorCode, config]) => {
+            const httpStatus = (config.httpStatus || this.guessHttpStatus(errorCode)).toString();
+            // Merge variables: global + per-code + built-in
+            const allVariables = {
+                ...globalVars,
+                ...config.variables,
+                ERROR_CODE: errorCode,
+                DESCRIPTION: config.description,
+                HTTP_STATUS: httpStatus,
+            };
+            const processedSchema = this.processTemplate(template, allVariables);
+            this.template.components.responses[httpStatus] = {
+                description: config.description,
+                content: {
+                    "application/json": {
+                        schema: processedSchema,
+                    },
+                },
+            };
+        });
+    }
+    processTemplate(template, variables) {
+        const jsonStr = JSON.stringify(template);
+        let result = jsonStr;
+        Object.entries(variables).forEach(([key, value]) => {
+            result = result.replace(new RegExp(`{{${key}}}`, "g"), value);
+        });
+        return JSON.parse(result);
+    }
+    guessHttpStatus(errorCode) {
+        const statusMap = {
+            bad: 400,
+            invalid: 400,
+            validation: 422,
+            unauthorized: 401,
+            auth: 401,
+            forbidden: 403,
+            permission: 403,
+            not_found: 404,
+            missing: 404,
+            conflict: 409,
+            duplicate: 409,
+            rate_limit: 429,
+            too_many: 429,
+            server: 500,
+            internal: 500,
+        };
+        for (const [key, status] of Object.entries(statusMap)) {
+            if (errorCode.toLowerCase().includes(key)) {
+                return status;
+            }
+        }
+        return 500;
+    }
+    createErrorResponseComponent(code, errorDef) {
+        return {
+            description: errorDef.description,
+            content: {
+                "application/json": {
+                    schema: errorDef.schema,
+                },
+            },
+        };
+    }
 }

package/dist/lib/route-processor.js

@@ -18,6 +18,91 @@ export class RouteProcessor {
         this.config = config;
         this.schemaProcessor = new SchemaProcessor(config.schemaDir, config.schemaType);
     }
+    buildResponsesFromConfig(dataTypes, method) {
+        const responses = {};
+        // 1. Add success response
+        const successCode = dataTypes.successCode || this.getDefaultSuccessCode(method);
+        if (dataTypes.responseType) {
+            const responseSchema = this.schemaProcessor.getSchemaContent({
+                responseType: dataTypes.responseType,
+            }).responses;
+            responses[successCode] = {
+                description: dataTypes.responseDescription || "Successful response",
+                content: {
+                    "application/json": {
+                        schema: responseSchema,
+                    },
+                },
+            };
+        }
+        // 2. Add responses from ResponseSet
+        const responseSetName = dataTypes.responseSet || this.config.defaultResponseSet;
+        if (responseSetName && responseSetName !== "none") {
+            const responseSets = this.config.responseSets || {};
+            const setNames = responseSetName.split(",").map((s) => s.trim());
+            setNames.forEach((setName) => {
+                const responseSet = responseSets[setName];
+                if (responseSet) {
+                    responseSet.forEach((errorCode) => {
+                        // Use $ref for components/responses
+                        responses[errorCode] = {
+                            $ref: `#/components/responses/${errorCode}`,
+                        };
+                    });
+                }
+            });
+        }
+        // 3. Add custom responses (@add)
+        if (dataTypes.addResponses) {
+            const customResponses = dataTypes.addResponses
+                .split(",")
+                .map((s) => s.trim());
+            customResponses.forEach((responseRef) => {
+                const [code, ref] = responseRef.split(":");
+                if (ref) {
+                    // Custom schema: "409:ConflictResponse"
+                    responses[code] = {
+                        description: this.getDefaultErrorDescription(code) || `HTTP ${code} response`,
+                        content: {
+                            "application/json": {
+                                schema: { $ref: `#/components/schemas/${ref}` },
+                            },
+                        },
+                    };
+                }
+                else {
+                    // Only code: "409" - use $ref fro components/responses
+                    responses[code] = {
+                        $ref: `#/components/responses/${code}`,
+                    };
+                }
+            });
+        }
+        return responses;
+    }
+    getDefaultSuccessCode(method) {
+        switch (method.toUpperCase()) {
+            case "POST":
+                return "201";
+            case "DELETE":
+                return "204";
+            default:
+                return "200";
+        }
+    }
+    getDefaultErrorDescription(code) {
+        const defaults = {
+            400: "Bad Request",
+            401: "Unauthorized",
+            403: "Forbidden",
+            404: "Not Found",
+            409: "Conflict",
+            422: "Unprocessable Entity",
+            429: "Too Many Requests",
+            500: "Internal Server Error",
+        };
+        return defaults[code] || `HTTP ${code}`;
+    }
     /**
      * Get the SchemaProcessor instance
      */
@@ -160,12 +245,16 @@ 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
-            ? this.schemaProcessor.createResponseSchema(responses, responseDescription)
-            : {};
+        definition.responses = this.buildResponsesFromConfig(dataTypes, method);
+        // If there are no responses from config, use the old logic
+        if (Object.keys(definition.responses).length === 0) {
+            definition.responses = responses
+                ? this.schemaProcessor.createResponseSchema(responses, responseDescription)
+                : {};
+        }
         this.swaggerPaths[routePath][method] = definition;
     }
     getRoutePath(filePath) {

package/dist/lib/schema-processor.js

@@ -501,6 +501,64 @@ 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";
+    }
+    createMultipleResponsesSchema(responses, defaultDescription) {
+        const result = {};
+        Object.entries(responses).forEach(([code, response]) => {
+            if (typeof response === "string") {
+                // Reference do components/responses
+                result[code] = { $ref: `#/components/responses/${response}` };
+            }
+            else {
+                result[code] = {
+                    description: response.description || defaultDescription || "Response",
+                    content: {
+                        "application/json": {
+                            schema: response.schema || response,
+                        },
+                    },
+                };
+            }
+        });
+        return result;
+    }
+    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
      */
@@ -558,18 +616,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

@@ -22,12 +22,16 @@ export function extractJSDocComments(path) {
     let paramsType = "";
     let pathParamsType = "";
     let bodyType = "";
-    let responseType = "";
     let auth = "";
     let isOpenApi = false;
     let deprecated = false;
     let bodyDescription = "";
+    let contentType = "";
+    let responseType = "";
     let responseDescription = "";
+    let responseSet = "";
+    let addResponses = "";
+    let successCode = "";
     if (comments) {
         comments.forEach((comment) => {
             const commentValue = cleanComment(comment.value);
@@ -42,13 +46,6 @@ export function extractJSDocComments(path) {
                     bodyDescription = match[1].trim();
                 }
             }
-            if (commentValue.includes("@responseDescription")) {
-                const regex = /@responseDescription\s*(.*)/;
-                const match = commentValue.match(regex);
-                if (match && match[1]) {
-                    responseDescription = match[1].trim();
-                }
-            }
             if (!summary) {
                 summary = commentValue.split("\n")[0];
             }
@@ -90,6 +87,45 @@ 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();
+                }
+            }
+            if (commentValue.includes("@responseDescription")) {
+                const regex = /@responseDescription\s*(.*)/;
+                const match = commentValue.match(regex);
+                if (match && match[1]) {
+                    responseDescription = match[1].trim();
+                }
+            }
+            if (commentValue.includes("@responseSet")) {
+                const regex = /@responseSet\s*(.*)/;
+                const match = commentValue.match(regex);
+                if (match && match[1]) {
+                    responseSet = match[1].trim();
+                }
+            }
+            if (commentValue.includes("@add")) {
+                const regex = /@add\s*(.*)/;
+                const match = commentValue.match(regex);
+                if (match && match[1]) {
+                    addResponses = match[1].trim();
+                }
+            }
+            if (commentValue.includes("@response")) {
+                const responseMatch = commentValue.match(/@response\s+(?:(\d+):)?(\w+)(?:\s+(.*))?/);
+                if (responseMatch) {
+                    const [, code, type] = responseMatch;
+                    successCode = code || "";
+                    responseType = type;
+                }
+                else {
+                    responseType = extractTypeFromComment(commentValue, "@response");
+                }
+            }
         });
     }
     return {
@@ -100,11 +136,15 @@ export function extractJSDocComments(path) {
         paramsType,
         pathParamsType,
         bodyType,
-        responseType,
         isOpenApi,
         deprecated,
         bodyDescription,
+        contentType,
+        responseType,
         responseDescription,
+        responseSet,
+        addResponses,
+        successCode,
     };
 }
 export function extractTypeFromComment(commentValue, tag) {
@@ -121,6 +161,10 @@ export function cleanSpec(spec) {
         "ui",
         "outputFile",
         "includeOpenApiRoutes",
+        "schemaType",
+        "defaultResponseSet",
+        "responseSets",
+        "errorConfig",
     ];
     const newSpec = { ...spec };
     propsToRemove.forEach((key) => delete newSpec[key]);

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/dist/openapi-template.js

@@ -20,6 +20,49 @@ export default {
             },
         },
     },
+    defaultResponseSet: "common",
+    responseSets: {
+        common: ["400", "500"],
+        auth: ["401"],
+    },
+    errorConfig: {
+        template: {
+            type: "object",
+            properties: {
+                success: {
+                    type: "boolean",
+                    example: false,
+                },
+                error: {
+                    type: "string",
+                    example: "{{ERROR_MESSAGE}}",
+                },
+            },
+        },
+        codes: {
+            invalid: {
+                description: "Bad request",
+                httpStatus: 400,
+                variables: {
+                    ERROR_MESSAGE: "Validation error",
+                },
+            },
+            auth: {
+                description: "Unauthorized",
+                httpStatus: 401,
+                variables: {
+                    ERROR_MESSAGE: "Unathorized",
+                },
+            },
+            server_error: {
+                description: "Internal server error",
+                httpStatus: 500,
+                variables: {
+                    ERROR_MESSAGE: "Something went wrong",
+                },
+            },
+        },
+    },
     apiDir: "./src/app/api",
     schemaDir: "./src",
     schemaType: "typescript",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.6.1",
+  "version": "0.6.4",
   "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",