next-openapi-gen 0.6.10 → 0.7.1
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 +49 -19
- package/dist/components/scalar.js +1 -0
- package/dist/lib/utils.js +6 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -150,22 +150,22 @@ export async function GET(
|
|
|
150
150
|
|
|
151
151
|
## JSDoc Documentation Tags
|
|
152
152
|
|
|
153
|
-
| Tag | Description
|
|
154
|
-
| ---------------------- |
|
|
155
|
-
| `@description` | Endpoint description
|
|
156
|
-
| `@pathParams` | Path parameters type/schema
|
|
157
|
-
| `@params` | Query parameters type/schema
|
|
158
|
-
| `@body` | Request body type/schema
|
|
159
|
-
| `@bodyDescription` | Request body description
|
|
160
|
-
| `@response` | Response type/schema
|
|
161
|
-
| `@responseDescription` | Response description
|
|
162
|
-
| `@responseSet` | Override default response set (`public`, `auth`, `none`)
|
|
163
|
-
| `@add` | Add custom response codes (`409:ConflictResponse`, `429`)
|
|
164
|
-
| `@contentType` | Request body content type (`application/json`, `multipart/form-data`)
|
|
165
|
-
| `@auth` | Authorization type (`bearer`, `basic`, `apikey`)
|
|
166
|
-
| `@tag` | Custom tag
|
|
167
|
-
| `@deprecated` | Marks the route as deprecated
|
|
168
|
-
| `@openapi` | Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled)
|
|
153
|
+
| Tag | Description |
|
|
154
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
155
|
+
| `@description` | Endpoint description |
|
|
156
|
+
| `@pathParams` | Path parameters type/schema |
|
|
157
|
+
| `@params` | Query parameters type/schema |
|
|
158
|
+
| `@body` | Request body type/schema |
|
|
159
|
+
| `@bodyDescription` | Request body description |
|
|
160
|
+
| `@response` | Response type/schema with optional code and description (`User`, `201:User`, `User:Description`, `201:User:Description`) |
|
|
161
|
+
| `@responseDescription` | Response description |
|
|
162
|
+
| `@responseSet` | Override default response set (`public`, `auth`, `none`) |
|
|
163
|
+
| `@add` | Add custom response codes (`409:ConflictResponse`, `429`) |
|
|
164
|
+
| `@contentType` | Request body content type (`application/json`, `multipart/form-data`) |
|
|
165
|
+
| `@auth` | Authorization type (`bearer`, `basic`, `apikey`) |
|
|
166
|
+
| `@tag` | Custom tag |
|
|
167
|
+
| `@deprecated` | Marks the route as deprecated |
|
|
168
|
+
| `@openapi` | Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled) |
|
|
169
169
|
|
|
170
170
|
## CLI Usage
|
|
171
171
|
|
|
@@ -307,6 +307,28 @@ type UserResponse = {
|
|
|
307
307
|
export async function GET() {
|
|
308
308
|
// ...
|
|
309
309
|
}
|
|
310
|
+
|
|
311
|
+
// Alternative formats with inline description
|
|
312
|
+
/**
|
|
313
|
+
* @response UserResponse:Returns user profile data
|
|
314
|
+
*/
|
|
315
|
+
export async function GET() {
|
|
316
|
+
// ...
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
/**
|
|
320
|
+
* @response 201:UserResponse:Returns newly created user
|
|
321
|
+
*/
|
|
322
|
+
export async function POST() {
|
|
323
|
+
// ...
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
/**
|
|
327
|
+
* @response 204:Empty:User successfully deleted
|
|
328
|
+
*/
|
|
329
|
+
export async function DELETE() {
|
|
330
|
+
// ...
|
|
331
|
+
}
|
|
310
332
|
```
|
|
311
333
|
|
|
312
334
|
### Authorization
|
|
@@ -409,6 +431,14 @@ Configure reusable error sets in `next.openapi.json`:
|
|
|
409
431
|
export async function GET() {}
|
|
410
432
|
// Generates: 200:UserResponse + common errors (400, 401, 500)
|
|
411
433
|
|
|
434
|
+
/**
|
|
435
|
+
* With custom description inline
|
|
436
|
+
* @response UserResponse:Complete user profile information
|
|
437
|
+
* @openapi
|
|
438
|
+
*/
|
|
439
|
+
export async function GET() {}
|
|
440
|
+
// Generates: 200:UserResponse (with custom description) + common errors
|
|
441
|
+
|
|
412
442
|
/**
|
|
413
443
|
* Override response set
|
|
414
444
|
* @response ProductResponse
|
|
@@ -419,13 +449,13 @@ export async function GET() {}
|
|
|
419
449
|
// Generates: 200:ProductResponse + public errors (400, 500)
|
|
420
450
|
|
|
421
451
|
/**
|
|
422
|
-
* Add custom responses
|
|
423
|
-
* @response 201:UserResponse
|
|
452
|
+
* Add custom responses with description
|
|
453
|
+
* @response 201:UserResponse:User created successfully
|
|
424
454
|
* @add 409:ConflictResponse
|
|
425
455
|
* @openapi
|
|
426
456
|
*/
|
|
427
457
|
export async function POST() {}
|
|
428
|
-
// Generates: 201:UserResponse + common errors + 409:ConflictResponse
|
|
458
|
+
// Generates: 201:UserResponse (with custom description) + common errors + 409:ConflictResponse
|
|
429
459
|
|
|
430
460
|
/**
|
|
431
461
|
* Combine multiple sets
|
package/dist/lib/utils.js
CHANGED
|
@@ -116,11 +116,15 @@ export function extractJSDocComments(path) {
|
|
|
116
116
|
}
|
|
117
117
|
}
|
|
118
118
|
if (commentValue.includes("@response")) {
|
|
119
|
-
const responseMatch = commentValue.match(/@response\s+(?:(\d+):)?(\w+)(
|
|
119
|
+
const responseMatch = commentValue.match(/@response\s+(?:(\d+):)?(\w+)(?::(.*))?/);
|
|
120
120
|
if (responseMatch) {
|
|
121
|
-
const [, code, type] = responseMatch;
|
|
121
|
+
const [, code, type, description] = responseMatch;
|
|
122
122
|
successCode = code || "";
|
|
123
123
|
responseType = type;
|
|
124
|
+
// Set responseDescription only if not already set by @responseDescription
|
|
125
|
+
if (description?.trim() && !responseDescription) {
|
|
126
|
+
responseDescription = description.trim();
|
|
127
|
+
}
|
|
124
128
|
}
|
|
125
129
|
else {
|
|
126
130
|
responseType = extractTypeFromComment(commentValue, "@response");
|
package/package.json
CHANGED