next-openapi-gen 1.0.0 → 1.0.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.
Files changed (2) hide show
  1. package/README.md +407 -0
  2. package/package.json +3 -2
package/README.md ADDED
@@ -0,0 +1,407 @@
1
+ # next-openapi-gen
2
+
3
+ [![npm version](https://img.shields.io/npm/v/next-openapi-gen)](https://www.npmjs.com/package/next-openapi-gen)
4
+ [![CI](https://github.com/tazo90/next-openapi-gen/actions/workflows/ci.yml/badge.svg)](https://github.com/tazo90/next-openapi-gen/actions/workflows/ci.yml)
5
+ [![License](https://img.shields.io/github/license/tazo90/next-openapi-gen)](https://github.com/tazo90/next-openapi-gen)
6
+
7
+ Generate OpenAPI `3.0`, `3.1`, and `3.2` from the routes and schemas you already have.
8
+
9
+ `next-openapi-gen` scans Next.js, TanStack Router, and React Router route handlers, reads JSDoc metadata, and generates an OpenAPI spec plus an optional docs UI. It is built for real codebases that use Zod, TypeScript, drizzle-zod, or reusable OpenAPI fragments, including mixed-schema migrations.
10
+
11
+ [Quick start](#quick-start) • [Docs index](./docs/README.md) • [Example apps](#example-apps) • [Validation and coverage](#validation-and-coverage)
12
+
13
+ ## Why teams use it
14
+
15
+ - Keep OpenAPI close to your handlers instead of maintaining a separate manual spec.
16
+ - Reuse existing `zod`, `typescript`, `drizzle-zod`, and YAML/JSON OpenAPI fragments in one pipeline.
17
+ - Target `3.0`, `3.1`, or `3.2` from the same route metadata with version-aware finalization.
18
+ - Ship interactive docs quickly with built-in UI scaffolding for Scalar, Swagger, Redoc, Stoplight Elements, or RapiDoc.
19
+ - Fall back on checker-assisted App Router response inference when explicit `@response` tags are missing.
20
+
21
+ ## Quick start
22
+
23
+ ### Requirements
24
+
25
+ - Node.js `>=24`
26
+ - A supported app framework:
27
+ - Next.js using App Router or Pages Router
28
+ - TanStack Router
29
+ - React Router
30
+
31
+ ### Install
32
+
33
+ ```bash
34
+ pnpm add -D next-openapi-gen
35
+ ```
36
+
37
+ ```bash
38
+ npm install --save-dev next-openapi-gen
39
+ ```
40
+
41
+ ```bash
42
+ yarn add --dev next-openapi-gen
43
+ ```
44
+
45
+ ### Initialize and generate
46
+
47
+ ```bash
48
+ # Next.js is the default framework
49
+ pnpm exec openapi-gen init
50
+
51
+ # Or choose another supported framework
52
+ pnpm exec openapi-gen init --framework tanstack
53
+ pnpm exec openapi-gen init --framework react-router
54
+
55
+ # Scans your routes and writes the spec once
56
+ pnpm exec openapi-gen generate
57
+
58
+ # Keeps the spec fresh during local development
59
+ pnpm exec openapi-gen generate --watch
60
+ ```
61
+
62
+ > [!TIP]
63
+ > Use `--ui none` during `init` if you only want the generated OpenAPI file.
64
+ >
65
+ > The package name is still `next-openapi-gen` during the transition. Config
66
+ > discovery also accepts the new `openapi-gen.config.ts` and
67
+ > `openapi-gen.config.json` aliases, while `next-openapi.config.*` and
68
+ > `next.openapi.json` continue to work with deprecation warnings. The legacy
69
+ > `next-openapi-gen` binary still works too, but `openapi-gen` is the preferred
70
+ > CLI name going forward.
71
+
72
+ Need the full setup flow, config walkthrough, or production notes? See
73
+ [docs/getting-started.md](./docs/getting-started.md).
74
+
75
+ ### What you get
76
+
77
+ - `next.openapi.json` in your project root
78
+ - `public/openapi.json` by default
79
+ - `/api-docs` with your selected UI provider by default
80
+
81
+ ## Framework support
82
+
83
+ | Framework | Setup path | Notes |
84
+ | --------------- | ----------------------------------------------------- | -------------------------------------------------------------- |
85
+ | Next.js | `pnpm exec openapi-gen init` | Supports App Router and Pages Router |
86
+ | TanStack Router | `pnpm exec openapi-gen init --framework tanstack` | Uses the public `next-openapi-gen/vite` plugin surface |
87
+ | React Router | `pnpm exec openapi-gen init --framework react-router` | Uses the public `next-openapi-gen/react-router` plugin surface |
88
+
89
+ ## Minimal example
90
+
91
+ ```ts
92
+ import { NextRequest } from "next/server";
93
+ import { z } from "zod";
94
+
95
+ export const ProductParams = z.object({
96
+ id: z.string().describe("Product ID"),
97
+ });
98
+
99
+ export const ProductResponse = z.object({
100
+ id: z.string(),
101
+ name: z.string(),
102
+ price: z.number().positive(),
103
+ });
104
+
105
+ /**
106
+ * Get product information
107
+ * @description Fetch a product by ID
108
+ * @pathParams ProductParams
109
+ * @response ProductResponse
110
+ * @openapi
111
+ */
112
+ export async function GET(request: NextRequest, { params }: { params: { id: string } }) {
113
+ return Response.json({ id: params.id, name: "Keyboard", price: 99 });
114
+ }
115
+ ```
116
+
117
+ ## Why `next-openapi-gen` is different
118
+
119
+ | Capability | Why it matters |
120
+ | ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
121
+ | Framework-aware route scanning | Covers Next.js, TanStack Router, and React Router with one generator and shared docs story. |
122
+ | Mixed schema sources | Combine `zod`, `typescript`, `schemaFiles`, and drizzle-zod-backed schemas during gradual migrations. |
123
+ | OpenAPI `3.0` / `3.1` / `3.2` targets | Keep one authoring flow while emitting version-aware output for newer spec features. |
124
+ | Response inference | Infer typed App Router responses when `@response` is omitted, while still letting explicit tags win. |
125
+ | Docs UI scaffolding | Generate a docs page fast instead of stopping at a JSON file. |
126
+
127
+ ## Common workflows
128
+
129
+ ### Start with Zod or TypeScript
130
+
131
+ Use one schema system if your app is already consistent:
132
+
133
+ ```json
134
+ {
135
+ "schemaType": "zod",
136
+ "schemaDir": "src/schemas"
137
+ }
138
+ ```
139
+
140
+ ### Migrate gradually with mixed schema sources
141
+
142
+ Use multiple schema types in the same project when you are moving from TypeScript to Zod or merging generated and hand-authored schemas:
143
+
144
+ ```json
145
+ {
146
+ "schemaType": ["zod", "typescript"],
147
+ "schemaDir": "./src/schemas",
148
+ "schemaFiles": ["./schemas/external-api.yaml"]
149
+ }
150
+ ```
151
+
152
+ Resolution priority is:
153
+
154
+ 1. `schemaFiles`
155
+ 2. `zod`
156
+ 3. `typescript`
157
+
158
+ See [apps/next-app-mixed-schemas](./apps/next-app-mixed-schemas) for a full working example.
159
+ For more adoption patterns, see
160
+ [docs/workflows-and-integrations.md](./docs/workflows-and-integrations.md).
161
+
162
+ ### Generate docs from Drizzle schemas
163
+
164
+ `next-openapi-gen` works well with `drizzle-zod`, so your database schema, validation, and API docs can share the same source of truth.
165
+
166
+ ```ts
167
+ import { createInsertSchema, createSelectSchema } from "drizzle-zod";
168
+ import { posts } from "@/db/schema";
169
+
170
+ export const CreatePostSchema = createInsertSchema(posts, {
171
+ title: (schema) => schema.title.min(5).max(255),
172
+ content: (schema) => schema.content.min(10),
173
+ });
174
+
175
+ export const PostResponseSchema = createSelectSchema(posts);
176
+ ```
177
+
178
+ See [apps/next-app-drizzle-zod](./apps/next-app-drizzle-zod) for the full CRUD example.
179
+
180
+ ### Rely on inference when you want less annotation
181
+
182
+ If you omit `@response`, App Router handlers can infer responses from typed `NextResponse.json(...)` and `Response.json(...)` returns.
183
+
184
+ ```ts
185
+ import { NextResponse } from "next/server";
186
+
187
+ type SearchResponse = {
188
+ total: number;
189
+ };
190
+
191
+ /**
192
+ * Search events
193
+ * @responseDescription Search result
194
+ * @openapi
195
+ */
196
+ export async function POST(): Promise<NextResponse<SearchResponse>> {
197
+ return NextResponse.json({ total: 3 });
198
+ }
199
+ ```
200
+
201
+ Explicit `@response` tags still take precedence when you want stable schema names or exact response codes.
202
+
203
+ ## Configuration
204
+
205
+ `init` creates a `next.openapi.json` file like this:
206
+
207
+ ```json
208
+ {
209
+ "openapi": "3.0.0",
210
+ "info": {
211
+ "title": "Next.js API",
212
+ "version": "1.0.0",
213
+ "description": "API generated by next-openapi-gen"
214
+ },
215
+ "apiDir": "src/app/api",
216
+ "routerType": "app",
217
+ "schemaDir": "src/schemas",
218
+ "schemaType": "zod",
219
+ "schemaFiles": [],
220
+ "outputFile": "openapi.json",
221
+ "outputDir": "./public",
222
+ "docsUrl": "api-docs",
223
+ "includeOpenApiRoutes": false,
224
+ "ignoreRoutes": [],
225
+ "debug": false
226
+ }
227
+ ```
228
+
229
+ Version guidance:
230
+
231
+ - Use `3.0.0` when you want the broadest downstream tooling compatibility.
232
+ - Use `3.1.0` when you want JSON Schema 2020-12-aligned output such as `jsonSchemaDialect`.
233
+ - Use `3.2.0` when you want first-class `querystring`, enhanced tag metadata, sequential media, and richer example objects.
234
+
235
+ ### Important options
236
+
237
+ | Option | Purpose |
238
+ | ------------------------------------- | ---------------------------------------------------------------- |
239
+ | `openapi` | Target `3.0.0`, `3.1.0`, or `3.2.0` output |
240
+ | `apiDir` | Route directory to scan |
241
+ | `routerType` | `"app"` or `"pages"` |
242
+ | `schemaDir` | Directory or directories to search for schemas/types |
243
+ | `schemaType` | `"zod"`, `"typescript"`, or both |
244
+ | `schemaFiles` | YAML/JSON OpenAPI fragments to merge into the generated document |
245
+ | `includeOpenApiRoutes` | Only include handlers tagged with `@openapi` |
246
+ | `ignoreRoutes` | Exclude routes with wildcard support |
247
+ | `defaultResponseSet` / `responseSets` | Reusable error-response groups |
248
+ | `errorConfig` | Shared error schema templates |
249
+
250
+ For a fuller setup guide, Pages Router notes, response sets, and route exclusion
251
+ patterns, see [docs/getting-started.md](./docs/getting-started.md).
252
+
253
+ ## JSDoc tags you will use most
254
+
255
+ | Tag | Purpose |
256
+ | -------------------------- | ---------------------------------------------------------------- |
257
+ | `@pathParams` | Path parameter schema or type |
258
+ | `@params` / `@queryParams` | Query parameter schema or type |
259
+ | `@body` | Request body schema or type |
260
+ | `@response` | Response schema, code, and optional description |
261
+ | `@responseDescription` | Response description without redefining the schema |
262
+ | `@auth` | Security requirement(s), including comma-separated alternatives |
263
+ | `@contentType` | Request content type such as `multipart/form-data` |
264
+ | `@examples` | Request, response, and querystring examples |
265
+ | `@openapi` | Explicit inclusion marker when `includeOpenApiRoutes` is enabled |
266
+ | `@ignore` | Exclude a route from generation |
267
+ | `@method` | Required HTTP method tag for Pages Router handlers |
268
+
269
+ For the complete tag guide and usage recipes, see
270
+ [docs/jsdoc-reference.md](./docs/jsdoc-reference.md).
271
+
272
+ OpenAPI `3.2`-specific tags such as `@querystring`, `@tagSummary`, `@tagKind`,
273
+ and sequential media annotations are documented in the same guide and shown in
274
+ [apps/next-app-zod](./apps/next-app-zod).
275
+
276
+ ## Compatibility
277
+
278
+ | Area | Support |
279
+ | --------------- | ------------------------------------------------------------ |
280
+ | Frameworks | Next.js, TanStack Router, React Router |
281
+ | Next.js routers | App Router and Pages Router |
282
+ | OpenAPI targets | `3.0`, `3.1`, `3.2` |
283
+ | Schema sources | `zod`, `typescript`, drizzle-zod output, YAML/JSON fragments |
284
+ | Docs UIs | Scalar, Swagger, Redoc, Stoplight Elements, RapiDoc |
285
+
286
+ For Pages Router projects, set `routerType` to `"pages"` and annotate handlers with `@method`. See [apps/next-pages-router](./apps/next-pages-router).
287
+
288
+ For the supported Zod 4 surface and known gaps, see
289
+ [docs/zod4-support-matrix.md](./docs/zod4-support-matrix.md).
290
+
291
+ ## Framework integrations
292
+
293
+ Use the integration that matches your framework:
294
+
295
+ - `next-openapi-gen/next`: Next.js adapter helpers such as `createNextOpenApiAdapter`
296
+ - `next-openapi-gen/vite`: Vite plugin surface used by the TanStack example app
297
+ - `next-openapi-gen/react-router`: React Router plugin surface
298
+
299
+ The main package export also exposes `generateProject`, `watchProject`, and
300
+ config helpers when you want to script generation directly.
301
+
302
+ ## Example apps
303
+
304
+ Use the checked-in examples to evaluate the tool in realistic setups:
305
+
306
+ - [apps/next-app-zod](./apps/next-app-zod): Zod-first App Router example
307
+ - [apps/next-app-next-config](./apps/next-app-next-config): typed config example targeting OpenAPI `3.1`
308
+ - [apps/next-app-typescript](./apps/next-app-typescript): TypeScript-first example
309
+ - [apps/next-app-mixed-schemas](./apps/next-app-mixed-schemas): mixed schema migration example
310
+ - [apps/next-app-drizzle-zod](./apps/next-app-drizzle-zod): Drizzle + drizzle-zod CRUD example
311
+ - [apps/next-app-sandbox](./apps/next-app-sandbox): edge-case route and exclusion playground
312
+ - [apps/next-app-ts-config](./apps/next-app-ts-config): typed config loading example
313
+ - [apps/next-app-adapter](./apps/next-app-adapter): Next adapter integration smoke example
314
+ - [apps/next-pages-router](./apps/next-pages-router): legacy Pages Router support
315
+ - [apps/tanstack-app](./apps/tanstack-app): TanStack Router framework parity example
316
+ - [apps/react-router-app](./apps/react-router-app): React Router framework parity example
317
+ - [apps/next-app-scalar](./apps/next-app-scalar), [apps/next-app-swagger](./apps/next-app-swagger): docs UI variants
318
+
319
+ ### Run an example
320
+
321
+ ```bash
322
+ pnpm install
323
+ cd apps/next-app-zod
324
+ pnpm exec openapi-gen generate
325
+ pnpm dev
326
+ ```
327
+
328
+ Then open `http://localhost:3000/api-docs`.
329
+
330
+ ## Validation and coverage
331
+
332
+ This repo is not just a demo. The CI pipeline covers:
333
+
334
+ - formatting and linting
335
+ - workspace builds
336
+ - unit tests
337
+ - integration tests
338
+ - coverage reporting
339
+ - Playwright E2E runs across an app matrix
340
+
341
+ For the detailed version matrix and validation notes, see:
342
+
343
+ - [docs/openapi-version-coverage.md](./docs/openapi-version-coverage.md)
344
+ - [docs/zod4-support-matrix.md](./docs/zod4-support-matrix.md)
345
+
346
+ The checked-in examples intentionally span different goals: most apps stay on
347
+ `3.0` as the conservative default, `apps/next-app-next-config` demonstrates a
348
+ typed `3.1` config, and `apps/next-app-zod` showcases richer `3.2` route and
349
+ document features.
350
+
351
+ ## Available UI providers
352
+
353
+ | Scalar | Swagger | Redoc | Stoplight Elements | RapiDoc |
354
+ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
355
+ | ![Scalar UI](https://raw.githubusercontent.com/tazo90/next-openapi-gen/main/assets/scalar.png) | ![Swagger UI](https://raw.githubusercontent.com/tazo90/next-openapi-gen/main/assets/swagger.png) | ![Redoc UI](https://raw.githubusercontent.com/tazo90/next-openapi-gen/main/assets/redoc.png) | ![Stoplight Elements UI](https://raw.githubusercontent.com/tazo90/next-openapi-gen/main/assets/stoplight.png) | ![RapiDoc UI](https://raw.githubusercontent.com/tazo90/next-openapi-gen/main/assets/rapidoc.png) |
356
+
357
+ ## Advanced docs
358
+
359
+ Use these deeper references when you need more than the quick start:
360
+
361
+ - [docs/README.md](./docs/README.md): docs index
362
+ - [docs/getting-started.md](./docs/getting-started.md): setup, config, framework defaults, watch mode, and production notes
363
+ - [docs/jsdoc-reference.md](./docs/jsdoc-reference.md): full route tag reference and examples
364
+ - [docs/workflows-and-integrations.md](./docs/workflows-and-integrations.md): framework integrations, mixed schemas, drizzle-zod, and downstream workflows
365
+ - [docs/faq.md](./docs/faq.md): troubleshooting and common questions
366
+ - [docs/openapi-version-coverage.md](./docs/openapi-version-coverage.md): version-specific behavior, validation strategy, and generated vs preserved fields
367
+ - [docs/zod4-support-matrix.md](./docs/zod4-support-matrix.md): tested Zod 4 coverage and known boundaries
368
+ - [docs/example-app-coverage-plan.md](./docs/example-app-coverage-plan.md): example app roles, coverage goals, and expansion roadmap
369
+ - [apps](./apps): complete runnable examples
370
+
371
+ ## CLI
372
+
373
+ ```bash
374
+ pnpm exec openapi-gen init
375
+ pnpm exec openapi-gen generate
376
+ pnpm exec openapi-gen generate --watch
377
+ ```
378
+
379
+ ### `init` options
380
+
381
+ | Option | Choices | Default |
382
+ | ------------- | ------------------------------------------------------------ | ------------------- |
383
+ | `--framework` | `next`, `tanstack`, `react-router` | `next` |
384
+ | `--ui` | `scalar`, `swagger`, `redoc`, `stoplight`, `rapidoc`, `none` | `scalar` |
385
+ | `--schema` | `zod`, `typescript` | `zod` |
386
+ | `--docs-url` | any string | `api-docs` |
387
+ | `--output` | any path | `next.openapi.json` |
388
+
389
+ ### `generate` options
390
+
391
+ | Option | Purpose |
392
+ | ------------ | --------------------------------------------- |
393
+ | `--config` | Use a specific config file |
394
+ | `--template` | Merge a specific OpenAPI template or fragment |
395
+ | `--watch` | Regenerate when routes or schema files change |
396
+
397
+ ## Contributing
398
+
399
+ Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, commit conventions, and workflow details.
400
+
401
+ ## Changelog
402
+
403
+ See [CHANGELOG.md](./CHANGELOG.md) for release history and recent changes.
404
+
405
+ ## License
406
+
407
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "next-openapi-gen",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Automatically generate OpenAPI 3.0, 3.1, and 3.2 documentation from Next.js projects, with support for Zod schemas, TypeScript types, and reusable OpenAPI fragments.",
5
5
  "keywords": [
6
6
  "api",
@@ -28,7 +28,8 @@
28
28
  },
29
29
  "files": [
30
30
  "dist",
31
- "templates"
31
+ "templates",
32
+ "README.md"
32
33
  ],
33
34
  "type": "module",
34
35
  "main": "dist/index.js",