{"id":17793371,"url":"https://github.com/tazo90/next-openapi-gen","last_synced_at":"2026-04-05T22:14:14.811Z","repository":{"id":257811846,"uuid":"867988719","full_name":"tazo90/next-openapi-gen","owner":"tazo90","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.","archived":false,"fork":false,"pushed_at":"2026-03-30T22:24:54.000Z","size":10801,"stargazers_count":163,"open_issues_count":14,"forks_count":24,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-31T00:28:06.834Z","etag":null,"topics":["api","api-docs","docs","drizzle","nextjs","openapi","reactjs","redoc","scalar","swagger","ts","typescript","zod"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/next-openapi-gen","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tazo90.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-10-05T07:13:48.000Z","updated_at":"2026-03-30T22:24:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"eb5173fa-b902-4bb1-8b46-5c108431e7b7","html_url":"https://github.com/tazo90/next-openapi-gen","commit_stats":null,"previous_names":["tazo90/next-openapi-gen"],"tags_count":83,"template":false,"template_full_name":null,"purl":"pkg:github/tazo90/next-openapi-gen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tazo90%2Fnext-openapi-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tazo90%2Fnext-openapi-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tazo90%2Fnext-openapi-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tazo90%2Fnext-openapi-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tazo90","download_url":"https://codeload.github.com/tazo90/next-openapi-gen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tazo90%2Fnext-openapi-gen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31257008,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-31T18:32:52.363Z","status":"ssl_error","status_checked_at":"2026-03-31T18:32:51.507Z","response_time":111,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-docs","docs","drizzle","nextjs","openapi","reactjs","redoc","scalar","swagger","ts","typescript","zod"],"created_at":"2024-10-27T11:08:11.797Z","updated_at":"2026-04-05T22:14:14.511Z","avatar_url":"https://github.com/tazo90.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# next-openapi-gen\n\n[![npm version](https://img.shields.io/npm/v/next-openapi-gen)](https://www.npmjs.com/package/next-openapi-gen)\n[![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)\n[![License](https://img.shields.io/github/license/tazo90/next-openapi-gen)](https://github.com/tazo90/next-openapi-gen)\n\nGenerate OpenAPI `3.0`, `3.1`, and `3.2` from the routes and schemas you already have.\n\n`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.\n\n[Quick start](#quick-start) • [Docs index](./docs/README.md) • [Example apps](#example-apps) • [Validation and coverage](#validation-and-coverage)\n\n## Why teams use it\n\n- Keep OpenAPI close to your handlers instead of maintaining a separate manual spec.\n- Reuse existing `zod`, `typescript`, `drizzle-zod`, and YAML/JSON OpenAPI fragments in one pipeline.\n- Target `3.0`, `3.1`, or `3.2` from the same route metadata with version-aware finalization.\n- Ship interactive docs quickly with built-in UI scaffolding for Scalar, Swagger, Redoc, Stoplight Elements, or RapiDoc.\n- Fall back on checker-assisted App Router response inference when explicit `@response` tags are missing.\n- Keep richer Zod 4 and TypeScript output in modern targets with selective runtime-assisted Zod export and checker fallback for advanced type constructs.\n\n## Quick start\n\n### Requirements\n\n- Node.js `\u003e=24`\n- A supported app framework:\n  - Next.js using App Router or Pages Router\n  - TanStack Router\n  - React Router\n\n### Install\n\n```bash\npnpm add -D next-openapi-gen\n```\n\n```bash\nnpm install --save-dev next-openapi-gen\n```\n\n```bash\nyarn add --dev next-openapi-gen\n```\n\n### Initialize and generate\n\n```bash\n# Next.js is the default framework\npnpm exec openapi-gen init\n\n# Or choose another supported framework\npnpm exec openapi-gen init --framework tanstack\npnpm exec openapi-gen init --framework react-router\n\n# Scans your routes and writes the spec once\npnpm exec openapi-gen generate\n\n# Keeps the spec fresh during local development\npnpm exec openapi-gen generate --watch\n```\n\n\u003e [!TIP]\n\u003e Use `--ui none` during `init` if you only want the generated OpenAPI file.\n\u003e\n\u003e The package name is still `next-openapi-gen` during the transition. Config\n\u003e discovery also accepts the new `openapi-gen.config.ts` and\n\u003e `openapi-gen.config.json` aliases, while `next-openapi.config.*` and\n\u003e `next.openapi.json` continue to work with deprecation warnings. The legacy\n\u003e `next-openapi-gen` binary still works too, but `openapi-gen` is the preferred\n\u003e CLI name going forward.\n\nNeed the full setup flow, config walkthrough, or production notes? See\n[docs/getting-started.md](./docs/getting-started.md).\n\n### What you get\n\n- `next.openapi.json` in your project root\n- `public/openapi.json` by default\n- `/api-docs` with your selected UI provider by default\n\n## Framework support\n\n| Framework       | Setup path                                            | Notes                                                          |\n| --------------- | ----------------------------------------------------- | -------------------------------------------------------------- |\n| Next.js         | `pnpm exec openapi-gen init`                          | Supports App Router and Pages Router                           |\n| TanStack Router | `pnpm exec openapi-gen init --framework tanstack`     | Uses the public `next-openapi-gen/vite` plugin surface         |\n| React Router    | `pnpm exec openapi-gen init --framework react-router` | Uses the public `next-openapi-gen/react-router` plugin surface |\n\n## Minimal example\n\n```ts\nimport { NextRequest } from \"next/server\";\nimport { z } from \"zod\";\n\nexport const ProductParams = z.object({\n  id: z.string().describe(\"Product ID\"),\n});\n\nexport const ProductResponse = z.object({\n  id: z.string(),\n  name: z.string(),\n  price: z.number().positive(),\n});\n\n/**\n * Get product information\n * @description Fetch a product by ID\n * @pathParams ProductParams\n * @response ProductResponse\n * @openapi\n */\nexport async function GET(request: NextRequest, { params }: { params: { id: string } }) {\n  return Response.json({ id: params.id, name: \"Keyboard\", price: 99 });\n}\n```\n\n## Why `next-openapi-gen` is different\n\n| Capability                            | Why it matters                                                                                        |\n| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |\n| Framework-aware route scanning        | Covers Next.js, TanStack Router, and React Router with one generator and shared docs story.           |\n| Mixed schema sources                  | Combine `zod`, `typescript`, `schemaFiles`, and drizzle-zod-backed schemas during gradual migrations. |\n| OpenAPI `3.0` / `3.1` / `3.2` targets | Keep one authoring flow while emitting version-aware output for newer spec features.                  |\n| Response inference                    | Infer typed App Router responses when `@response` is omitted, while still letting explicit tags win.  |\n| Docs UI scaffolding                   | Generate a docs page fast instead of stopping at a JSON file.                                         |\n\n## Common workflows\n\n### Start with Zod or TypeScript\n\nUse one schema system if your app is already consistent:\n\n```json\n{\n  \"schemaType\": \"zod\",\n  \"schemaDir\": \"src/schemas\"\n}\n```\n\n### Migrate gradually with mixed schema sources\n\nUse multiple schema types in the same project when you are moving from TypeScript to Zod or merging generated and hand-authored schemas:\n\n```json\n{\n  \"schemaType\": [\"zod\", \"typescript\"],\n  \"schemaDir\": \"./src/schemas\",\n  \"schemaFiles\": [\"./schemas/external-api.yaml\"]\n}\n```\n\nResolution priority is:\n\n1. `schemaFiles`\n2. `zod`\n3. `typescript`\n\nSee [apps/next-app-mixed-schemas](./apps/next-app-mixed-schemas) for a full working example.\nFor more adoption patterns, see\n[docs/workflows-and-integrations.md](./docs/workflows-and-integrations.md).\n\nWhen you target modern OpenAPI output, the Zod path can also split request and response component refs when a supported Zod 4 schema emits different input and output JSON Schema shapes, while the TypeScript path can use selective checker fallback for mapped, conditional, template-literal, and import-based named types.\n\n### Generate docs from Drizzle schemas\n\n`next-openapi-gen` works well with `drizzle-zod`, so your database schema, validation, and API docs can share the same source of truth.\n\n```ts\nimport { createInsertSchema, createSelectSchema } from \"drizzle-zod\";\nimport { posts } from \"@/db/schema\";\n\nexport const CreatePostSchema = createInsertSchema(posts, {\n  title: (schema) =\u003e schema.title.min(5).max(255),\n  content: (schema) =\u003e schema.content.min(10),\n});\n\nexport const PostResponseSchema = createSelectSchema(posts);\n```\n\nSee [apps/next-app-drizzle-zod](./apps/next-app-drizzle-zod) for the full CRUD example.\n\n### Rely on inference when you want less annotation\n\nIf you omit `@response`, App Router handlers can infer responses from typed `NextResponse.json(...)` and `Response.json(...)` returns.\n\n```ts\nimport { NextResponse } from \"next/server\";\n\ntype SearchResponse = {\n  total: number;\n};\n\n/**\n * Search events\n * @responseDescription Search result\n * @openapi\n */\nexport async function POST(): Promise\u003cNextResponse\u003cSearchResponse\u003e\u003e {\n  return NextResponse.json({ total: 3 });\n}\n```\n\nExplicit `@response` tags still take precedence when you want stable schema names or exact response codes.\n\n## Configuration\n\n`init` creates a `next.openapi.json` file like this:\n\n```json\n{\n  \"openapi\": \"3.0.0\",\n  \"info\": {\n    \"title\": \"Next.js API\",\n    \"version\": \"1.0.0\",\n    \"description\": \"API generated by next-openapi-gen\"\n  },\n  \"apiDir\": \"src/app/api\",\n  \"routerType\": \"app\",\n  \"schemaDir\": \"src/schemas\",\n  \"schemaType\": \"zod\",\n  \"schemaFiles\": [],\n  \"outputFile\": \"openapi.json\",\n  \"outputDir\": \"./public\",\n  \"docsUrl\": \"api-docs\",\n  \"includeOpenApiRoutes\": false,\n  \"ignoreRoutes\": [],\n  \"debug\": false\n}\n```\n\nVersion guidance:\n\n- Use `3.0.0` when you want the broadest downstream tooling compatibility.\n- Use `3.1.0` when you want JSON Schema 2020-12-aligned output such as `jsonSchemaDialect`.\n- Use `3.2.0` when you want first-class `querystring`, enhanced tag metadata, sequential media, and richer example objects.\n\n### Important options\n\n| Option                                | Purpose                                                          |\n| ------------------------------------- | ---------------------------------------------------------------- |\n| `openapi`                             | Target `3.0.0`, `3.1.0`, or `3.2.0` output                       |\n| `apiDir`                              | Route directory to scan                                          |\n| `routerType`                          | `\"app\"` or `\"pages\"`                                             |\n| `schemaDir`                           | Directory or directories to search for schemas/types             |\n| `schemaType`                          | `\"zod\"`, `\"typescript\"`, or both                                 |\n| `schemaFiles`                         | YAML/JSON OpenAPI fragments to merge into the generated document |\n| `includeOpenApiRoutes`                | Only include handlers tagged with `@openapi`                     |\n| `ignoreRoutes`                        | Exclude routes with wildcard support                             |\n| `defaultResponseSet` / `responseSets` | Reusable error-response groups                                   |\n| `errorConfig`                         | Shared error schema templates                                    |\n\nFor a fuller setup guide, Pages Router notes, response sets, and route exclusion\npatterns, see [docs/getting-started.md](./docs/getting-started.md).\n\n## JSDoc tags you will use most\n\n| Tag                        | Purpose                                                          |\n| -------------------------- | ---------------------------------------------------------------- |\n| `@pathParams`              | Path parameter schema or type                                    |\n| `@params` / `@queryParams` | Query parameter schema or type                                   |\n| `@body`                    | Request body schema or type                                      |\n| `@response`                | Response schema, code, and optional description                  |\n| `@responseDescription`     | Response description without redefining the schema               |\n| `@auth`                    | Security requirement(s), including comma-separated alternatives  |\n| `@contentType`             | Request content type such as `multipart/form-data`               |\n| `@examples`                | Request, response, and querystring examples                      |\n| `@openapi`                 | Explicit inclusion marker when `includeOpenApiRoutes` is enabled |\n| `@ignore`                  | Exclude a route from generation                                  |\n| `@method`                  | Required HTTP method tag for Pages Router handlers               |\n\nFor the complete tag guide and usage recipes, see\n[docs/jsdoc-reference.md](./docs/jsdoc-reference.md).\n\nOpenAPI `3.2`-specific tags such as `@querystring`, `@tagSummary`, `@tagKind`,\nand sequential media annotations are documented in the same guide and shown in\n[apps/next-app-zod](./apps/next-app-zod).\n\n## Compatibility\n\n| Area            | Support                                                      |\n| --------------- | ------------------------------------------------------------ |\n| Frameworks      | Next.js, TanStack Router, React Router                       |\n| Next.js routers | App Router and Pages Router                                  |\n| OpenAPI targets | `3.0`, `3.1`, `3.2`                                          |\n| Schema sources  | `zod`, `typescript`, drizzle-zod output, YAML/JSON fragments |\n| Docs UIs        | Scalar, Swagger, Redoc, Stoplight Elements, RapiDoc          |\n\nFor Pages Router projects, set `routerType` to `\"pages\"` and annotate handlers with `@method`. See [apps/next-pages-router](./apps/next-pages-router).\n\nFor the supported Zod 4 surface and known gaps, see\n[docs/zod4-support-matrix.md](./docs/zod4-support-matrix.md).\n\n## Framework integrations\n\nUse the integration that matches your framework:\n\n- `next-openapi-gen/next`: Next.js adapter helpers such as `createNextOpenApiAdapter`\n- `next-openapi-gen/vite`: Vite plugin surface used by the TanStack example app\n- `next-openapi-gen/react-router`: React Router plugin surface\n\nThe main package export also exposes `generateProject`, `watchProject`, and\nconfig helpers when you want to script generation directly.\n\n## Example apps\n\nUse the checked-in examples to evaluate the tool in realistic setups:\n\n- [apps/next-app-zod](./apps/next-app-zod): Zod-first App Router example\n- [apps/next-app-next-config](./apps/next-app-next-config): typed config example targeting OpenAPI `3.1`\n- [apps/next-app-typescript](./apps/next-app-typescript): TypeScript-first example\n- [apps/next-app-mixed-schemas](./apps/next-app-mixed-schemas): mixed schema migration example\n- [apps/next-app-drizzle-zod](./apps/next-app-drizzle-zod): Drizzle + drizzle-zod CRUD example\n- [apps/next-app-sandbox](./apps/next-app-sandbox): edge-case route and exclusion playground\n- [apps/next-app-ts-config](./apps/next-app-ts-config): typed config loading example\n- [apps/next-app-adapter](./apps/next-app-adapter): Next adapter integration smoke example\n- [apps/next-pages-router](./apps/next-pages-router): legacy Pages Router support\n- [apps/tanstack-app](./apps/tanstack-app): TanStack Router framework parity example\n- [apps/react-router-app](./apps/react-router-app): React Router framework parity example\n- [apps/next-app-scalar](./apps/next-app-scalar), [apps/next-app-swagger](./apps/next-app-swagger): docs UI variants\n\n### Run an example\n\n```bash\npnpm install\ncd apps/next-app-zod\npnpm exec openapi-gen generate\npnpm dev\n```\n\nThen open `http://localhost:3000/api-docs`.\n\n## Validation and coverage\n\nThis repo is not just a demo. The CI pipeline covers:\n\n- formatting and linting\n- workspace builds\n- unit tests\n- integration tests\n- coverage reporting\n- Playwright E2E runs across an app matrix\n\nFor the detailed version matrix and validation notes, see:\n\n- [docs/openapi-version-coverage.md](./docs/openapi-version-coverage.md)\n- [docs/zod4-support-matrix.md](./docs/zod4-support-matrix.md)\n\nThe checked-in examples intentionally span different goals: most apps stay on\n`3.0` as the conservative default, `apps/next-app-next-config` demonstrates a\ntyped `3.1` config, and `apps/next-app-zod` showcases richer `3.2` route and\ndocument features.\n\n## Available UI providers\n\n| Scalar                                                                                         | Swagger                                                                                          | Redoc                                                                                        | Stoplight Elements                                                                                            | RapiDoc                                                                                          |\n| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| ![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) |\n\n## Advanced docs\n\nUse these deeper references when you need more than the quick start:\n\n- [docs/README.md](./docs/README.md): docs index\n- [docs/getting-started.md](./docs/getting-started.md): setup, config, framework defaults, watch mode, and production notes\n- [docs/jsdoc-reference.md](./docs/jsdoc-reference.md): full route tag reference and examples\n- [docs/workflows-and-integrations.md](./docs/workflows-and-integrations.md): framework integrations, mixed schemas, drizzle-zod, and downstream workflows\n- [docs/faq.md](./docs/faq.md): troubleshooting and common questions\n- [docs/openapi-version-coverage.md](./docs/openapi-version-coverage.md): version-specific behavior, validation strategy, and generated vs preserved fields\n- [docs/zod4-support-matrix.md](./docs/zod4-support-matrix.md): tested Zod 4 coverage and known boundaries\n- [docs/example-app-coverage-plan.md](./docs/example-app-coverage-plan.md): example app roles, coverage goals, and expansion roadmap\n- [apps](./apps): complete runnable examples\n\n## CLI\n\n```bash\npnpm exec openapi-gen init\npnpm exec openapi-gen generate\npnpm exec openapi-gen generate --watch\n```\n\n### `init` options\n\n| Option        | Choices                                                      | Default             |\n| ------------- | ------------------------------------------------------------ | ------------------- |\n| `--framework` | `next`, `tanstack`, `react-router`                           | `next`              |\n| `--ui`        | `scalar`, `swagger`, `redoc`, `stoplight`, `rapidoc`, `none` | `scalar`            |\n| `--schema`    | `zod`, `typescript`                                          | `zod`               |\n| `--docs-url`  | any string                                                   | `api-docs`          |\n| `--output`    | any path                                                     | `next.openapi.json` |\n\n### `generate` options\n\n| Option       | Purpose                                       |\n| ------------ | --------------------------------------------- |\n| `--config`   | Use a specific config file                    |\n| `--template` | Merge a specific OpenAPI template or fragment |\n| `--watch`    | Regenerate when routes or schema files change |\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, commit conventions, and workflow details.\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for release history and recent changes.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftazo90%2Fnext-openapi-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftazo90%2Fnext-openapi-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftazo90%2Fnext-openapi-gen/lists"}