next-openapi-gen 0.5.3 → 0.5.5

package/README.md

@@ -57,7 +57,7 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
     }
   ],
   "apiDir": "src/app/api",
-  "schemaDir": "src/types", // or e.g. "src/schemas" for Zod schemas
+  "schemaDir": "src/types", // or "src/schemas" for Zod schemas
   "schemaType": "typescript", // or "zod" for Zod schemas
   "outputFile": "openapi.json",
   "docsUrl": "/api-docs",
@@ -145,16 +145,19 @@ export async function GET(
 
 ## JSDoc Documentation Tags
 
-| Tag           | Description                                                                         |
-| ------------- | ----------------------------------------------------------------------------------- |
-| `@desc`       | Endpoint description                                                                |
-| `@pathParams` | Path parameters type/schema                                                         |
-| `@params`     | Query parameters type/schema                                                        |
-| `@body`       | Request body type/schema                                                            |
-| `@response`   | Response type/schema                                                                |
-| `@auth`       | Authorization type (`bearer`, `basic`, `apikey`)                                    |
-| `@tag`        | Custom tag                                                                          |
-| `@openapi`    | Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled) |
+| Tag                    | Description                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------- |
+| `@desc`                | Endpoint description                                                                |
+| `@pathParams`          | Path parameters type/schema                                                         |
+| `@params`              | Query parameters type/schema                                                        |
+| `@body`                | Request body type/schema                                                            |
+| `@bodyDescription`     | Request body description                                                            |
+| `@response`            | Response type/schema                                                                |
+| `@responseDescription` | Response description                                                                |
+| `@auth`                | Authorization type (`bearer`, `basic`, `apikey`)                                    |
+| `@tag`                 | Custom tag                                                                          |
+| `@deprecated`          | Marks the route as deprecated                                                       |
+| `@openapi`             | Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled) |
 
 ## CLI Usage
 
@@ -260,6 +263,7 @@ const CreateUserBody = z.object({
 
 /**
  * @body CreateUserBody
+ * @bodyDescription User registration data including email and password
  */
 export async function POST() {
   // ...
@@ -289,6 +293,7 @@ const UserResponse = z.object({
 
 /**
  * @response UserResponse
+ * @responseDescription Returns newly created user object
  */
 export async function GET() {
   // ...
@@ -308,6 +313,36 @@ export async function GET() {
 }
 ```
 
+### Deprecated
+
+```typescript
+// src/app/api/v1/route.ts
+
+// TypeScript
+type UserResponse = {
+  id: string;
+  name: string;
+  /** @deprecated Use firstName and lastName instead */
+  fullName?: string;
+  email: string;
+};
+
+// Or Zod
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  fullName: z.string().optional().describe("@deprecated Use name instead"),
+  email: z.string().email(),
+});
+
+/**
+ * @response UserResponse
+ */
+export async function GET() {
+  // ...
+}
+```
+
 ## Advanced Usage
 
 ### Automatic Path Parameter Detection
@@ -370,7 +405,7 @@ const UserSchema = z.object({
 // Use z.infer to create a TypeScript type
 type User = z.infer<typeof UserSchema>;
 
-// The library will be able to recognize this schema by reference
+// The library will be able to recognize this schema by reference `UserSchema` or `User` type.
 ```
 
 ## Available UI providers

package/dist/lib/route-processor.js

@@ -109,7 +109,7 @@ export class RouteProcessor {
         const routePath = this.getRoutePath(filePath);
         const rootPath = capitalize(routePath.split("/")[1]);
         const operationId = getOperationId(routePath, method);
-        const { tag, summary, description, auth, isOpenApi } = dataTypes;
+        const { tag, summary, description, auth, isOpenApi, deprecated, bodyDescription, responseDescription, } = dataTypes;
         if (this.config.includeOpenApiRoutes && !isOpenApi) {
             // If flag is enabled and there is no @openapi tag, then skip path
             return;
@@ -125,6 +125,9 @@ export class RouteProcessor {
             tags: [tag || rootPath],
             parameters: [],
         };
+        if (deprecated) {
+            definition.deprecated = true;
+        }
         // Add auth
         if (auth) {
             definition.security = [
@@ -157,12 +160,11 @@ export class RouteProcessor {
         }
         // Add request body
         if (MUTATION_HTTP_METHODS.includes(method.toUpperCase())) {
-            definition.requestBody =
-                this.schemaProcessor.createRequestBodySchema(body);
+            definition.requestBody = this.schemaProcessor.createRequestBodySchema(body, bodyDescription);
         }
         // Add responses
         definition.responses = responses
-            ? this.schemaProcessor.createResponseSchema(responses)
+            ? this.schemaProcessor.createResponseSchema(responses, responseDescription)
             : {};
         this.swaggerPaths[routePath][method] = definition;
     }

package/dist/lib/schema-processor.js

@@ -555,19 +555,23 @@ export class SchemaProcessor {
         }
         return queryParams;
     }
-    createRequestBodySchema(body) {
-        return {
+    createRequestBodySchema(body, description) {
+        const schema = {
             content: {
                 "application/json": {
                     schema: body,
                 },
             },
         };
+        if (description) {
+            schema.description = description;
+        }
+        return schema;
     }
-    createResponseSchema(responses) {
+    createResponseSchema(responses, description) {
         return {
             200: {
-                description: "Successful response",
+                description: description || "Successful response",
                 content: {
                     "application/json": {
                         schema: responses,

package/dist/lib/utils.js

@@ -25,10 +25,30 @@ export function extractJSDocComments(path) {
     let responseType = "";
     let auth = "";
     let isOpenApi = false;
+    let deprecated = false;
+    let bodyDescription = "";
+    let responseDescription = "";
     if (comments) {
         comments.forEach((comment) => {
             const commentValue = cleanComment(comment.value);
             isOpenApi = commentValue.includes("@openapi");
+            if (commentValue.includes("@deprecated")) {
+                deprecated = true;
+            }
+            if (commentValue.includes("@bodyDescription")) {
+                const regex = /@bodyDescription\s*(.*)/;
+                const match = commentValue.match(regex);
+                if (match && match[1]) {
+                    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];
             }
@@ -82,6 +102,9 @@ export function extractJSDocComments(path) {
         bodyType,
         responseType,
         isOpenApi,
+        deprecated,
+        bodyDescription,
+        responseDescription,
     };
 }
 export function extractTypeFromComment(commentValue, tag) {

package/dist/lib/zod-converter.js

@@ -874,9 +874,21 @@ export class ZodSchemaConverter {
                 break;
             case "describe":
                 if (node.arguments.length > 0 && t.isStringLiteral(node.arguments[0])) {
-                    schema.description = node.arguments[0].value;
+                    const description = node.arguments[0].value;
+                    // Check if description includes @deprecated
+                    if (description.startsWith("@deprecated")) {
+                        schema.deprecated = true;
+                        // Remove @deprecated from description
+                        schema.description = description.replace("@deprecated", "").trim();
+                    }
+                    else {
+                        schema.description = description;
+                    }
                 }
                 break;
+            case "deprecated":
+                schema.deprecated = true;
+                break;
             case "min":
                 if (node.arguments.length > 0 &&
                     t.isNumericLiteral(node.arguments[0])) {

package/package.json

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