next-openapi-gen 0.5.4 → 0.5.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -14
- package/dist/lib/utils.js +2 -2
- package/dist/lib/zod-converter.js +10 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -57,7 +57,7 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
|
|
|
57
57
|
}
|
|
58
58
|
],
|
|
59
59
|
"apiDir": "src/app/api",
|
|
60
|
-
"schemaDir": "src/types", // or
|
|
60
|
+
"schemaDir": "src/types", // or "src/schemas" for Zod schemas
|
|
61
61
|
"schemaType": "typescript", // or "zod" for Zod schemas
|
|
62
62
|
"outputFile": "openapi.json",
|
|
63
63
|
"docsUrl": "/api-docs",
|
|
@@ -97,7 +97,7 @@ type UserResponse = {
|
|
|
97
97
|
|
|
98
98
|
/**
|
|
99
99
|
* Get user information
|
|
100
|
-
* @
|
|
100
|
+
* @description Fetches detailed user information by ID
|
|
101
101
|
* @pathParams UserParams
|
|
102
102
|
* @response UserResponse
|
|
103
103
|
* @openapi
|
|
@@ -130,7 +130,7 @@ export const ProductResponse = z.object({
|
|
|
130
130
|
|
|
131
131
|
/**
|
|
132
132
|
* Get product information
|
|
133
|
-
* @
|
|
133
|
+
* @description Fetches detailed product information by ID
|
|
134
134
|
* @pathParams ProductParams
|
|
135
135
|
* @response ProductResponse
|
|
136
136
|
* @openapi
|
|
@@ -145,16 +145,19 @@ export async function GET(
|
|
|
145
145
|
|
|
146
146
|
## JSDoc Documentation Tags
|
|
147
147
|
|
|
148
|
-
| Tag
|
|
149
|
-
|
|
|
150
|
-
| `@
|
|
151
|
-
| `@pathParams`
|
|
152
|
-
| `@params`
|
|
153
|
-
| `@body`
|
|
154
|
-
| `@
|
|
155
|
-
| `@
|
|
156
|
-
| `@
|
|
157
|
-
| `@
|
|
148
|
+
| Tag | Description |
|
|
149
|
+
| ---------------------- | ----------------------------------------------------------------------------------- |
|
|
150
|
+
| `@description` | Endpoint description |
|
|
151
|
+
| `@pathParams` | Path parameters type/schema |
|
|
152
|
+
| `@params` | Query parameters type/schema |
|
|
153
|
+
| `@body` | Request body type/schema |
|
|
154
|
+
| `@bodyDescription` | Request body description |
|
|
155
|
+
| `@response` | Response type/schema |
|
|
156
|
+
| `@responseDescription` | Response description |
|
|
157
|
+
| `@auth` | Authorization type (`bearer`, `basic`, `apikey`) |
|
|
158
|
+
| `@tag` | Custom tag |
|
|
159
|
+
| `@deprecated` | Marks the route as deprecated |
|
|
160
|
+
| `@openapi` | Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled) |
|
|
158
161
|
|
|
159
162
|
## CLI Usage
|
|
160
163
|
|
|
@@ -260,6 +263,7 @@ const CreateUserBody = z.object({
|
|
|
260
263
|
|
|
261
264
|
/**
|
|
262
265
|
* @body CreateUserBody
|
|
266
|
+
* @bodyDescription User registration data including email and password
|
|
263
267
|
*/
|
|
264
268
|
export async function POST() {
|
|
265
269
|
// ...
|
|
@@ -289,6 +293,7 @@ const UserResponse = z.object({
|
|
|
289
293
|
|
|
290
294
|
/**
|
|
291
295
|
* @response UserResponse
|
|
296
|
+
* @responseDescription Returns newly created user object
|
|
292
297
|
*/
|
|
293
298
|
export async function GET() {
|
|
294
299
|
// ...
|
|
@@ -308,6 +313,37 @@ export async function GET() {
|
|
|
308
313
|
}
|
|
309
314
|
```
|
|
310
315
|
|
|
316
|
+
### Deprecated
|
|
317
|
+
|
|
318
|
+
```typescript
|
|
319
|
+
// src/app/api/v1/route.ts
|
|
320
|
+
|
|
321
|
+
// TypeScript
|
|
322
|
+
type UserResponse = {
|
|
323
|
+
id: string;
|
|
324
|
+
name: string;
|
|
325
|
+
/** @deprecated Use firstName and lastName instead */
|
|
326
|
+
fullName?: string;
|
|
327
|
+
email: string;
|
|
328
|
+
};
|
|
329
|
+
|
|
330
|
+
// Or Zod
|
|
331
|
+
const UserSchema = z.object({
|
|
332
|
+
id: z.string(),
|
|
333
|
+
name: z.string(),
|
|
334
|
+
fullName: z.string().optional().describe("@deprecated Use name instead"),
|
|
335
|
+
email: z.string().email(),
|
|
336
|
+
});
|
|
337
|
+
|
|
338
|
+
/**
|
|
339
|
+
* @body UserSchema
|
|
340
|
+
* @response UserResponse
|
|
341
|
+
*/
|
|
342
|
+
export async function GET() {
|
|
343
|
+
// ...
|
|
344
|
+
}
|
|
345
|
+
```
|
|
346
|
+
|
|
311
347
|
## Advanced Usage
|
|
312
348
|
|
|
313
349
|
### Automatic Path Parameter Detection
|
|
@@ -370,7 +406,7 @@ const UserSchema = z.object({
|
|
|
370
406
|
// Use z.infer to create a TypeScript type
|
|
371
407
|
type User = z.infer<typeof UserSchema>;
|
|
372
408
|
|
|
373
|
-
// The library will be able to recognize this schema by reference
|
|
409
|
+
// The library will be able to recognize this schema by reference `UserSchema` or `User` type.
|
|
374
410
|
```
|
|
375
411
|
|
|
376
412
|
## Available UI providers
|
package/dist/lib/utils.js
CHANGED
|
@@ -67,8 +67,8 @@ export function extractJSDocComments(path) {
|
|
|
67
67
|
break;
|
|
68
68
|
}
|
|
69
69
|
}
|
|
70
|
-
if (commentValue.includes("@
|
|
71
|
-
const regex = /@
|
|
70
|
+
if (commentValue.includes("@description")) {
|
|
71
|
+
const regex = /@description\s*(.*)/;
|
|
72
72
|
description = commentValue.match(regex)[1].trim();
|
|
73
73
|
}
|
|
74
74
|
if (commentValue.includes("@tag")) {
|
|
@@ -874,7 +874,16 @@ export class ZodSchemaConverter {
|
|
|
874
874
|
break;
|
|
875
875
|
case "describe":
|
|
876
876
|
if (node.arguments.length > 0 && t.isStringLiteral(node.arguments[0])) {
|
|
877
|
-
|
|
877
|
+
const description = node.arguments[0].value;
|
|
878
|
+
// Check if description includes @deprecated
|
|
879
|
+
if (description.startsWith("@deprecated")) {
|
|
880
|
+
schema.deprecated = true;
|
|
881
|
+
// Remove @deprecated from description
|
|
882
|
+
schema.description = description.replace("@deprecated", "").trim();
|
|
883
|
+
}
|
|
884
|
+
else {
|
|
885
|
+
schema.description = description;
|
|
886
|
+
}
|
|
878
887
|
}
|
|
879
888
|
break;
|
|
880
889
|
case "deprecated":
|
package/package.json
CHANGED