next-openapi-gen 0.5.4 → 0.5.5
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 +47 -12
- 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",
|
|
@@ -145,16 +145,19 @@ export async function GET(
|
|
|
145
145
|
|
|
146
146
|
## JSDoc Documentation Tags
|
|
147
147
|
|
|
148
|
-
| Tag
|
|
149
|
-
|
|
|
150
|
-
| `@desc`
|
|
151
|
-
| `@pathParams`
|
|
152
|
-
| `@params`
|
|
153
|
-
| `@body`
|
|
154
|
-
| `@
|
|
155
|
-
| `@
|
|
156
|
-
| `@
|
|
157
|
-
| `@
|
|
148
|
+
| Tag | Description |
|
|
149
|
+
| ---------------------- | ----------------------------------------------------------------------------------- |
|
|
150
|
+
| `@desc` | 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,36 @@ 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
|
+
* @response UserResponse
|
|
340
|
+
*/
|
|
341
|
+
export async function GET() {
|
|
342
|
+
// ...
|
|
343
|
+
}
|
|
344
|
+
```
|
|
345
|
+
|
|
311
346
|
## Advanced Usage
|
|
312
347
|
|
|
313
348
|
### Automatic Path Parameter Detection
|
|
@@ -370,7 +405,7 @@ const UserSchema = z.object({
|
|
|
370
405
|
// Use z.infer to create a TypeScript type
|
|
371
406
|
type User = z.infer<typeof UserSchema>;
|
|
372
407
|
|
|
373
|
-
// The library will be able to recognize this schema by reference
|
|
408
|
+
// The library will be able to recognize this schema by reference `UserSchema` or `User` type.
|
|
374
409
|
```
|
|
375
410
|
|
|
376
411
|
## Available UI providers
|
|
@@ -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