{"id":15782877,"url":"https://github.com/omermecitoglu/next-openapi-json-generator","last_synced_at":"2026-01-03T07:00:56.042Z","repository":{"id":242827367,"uuid":"810273148","full_name":"omermecitoglu/next-openapi-json-generator","owner":"omermecitoglu","description":"a Next.js plugin to generate OpenAPI documentation from route handlers","archived":false,"fork":false,"pushed_at":"2024-12-13T04:14:55.000Z","size":433,"stargazers_count":7,"open_issues_count":7,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-10T14:55:26.801Z","etag":null,"topics":["generator","next","nextjs","openapi","openapi-json","self-documenting","swagger","swagger-json","ts","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omermecitoglu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-06-04T11:32:13.000Z","updated_at":"2025-03-04T12:58:53.000Z","dependencies_parsed_at":"2024-11-07T10:38:44.828Z","dependency_job_id":null,"html_url":"https://github.com/omermecitoglu/next-openapi-json-generator","commit_stats":{"total_commits":72,"total_committers":2,"mean_commits":36.0,"dds":0.01388888888888884,"last_synced_commit":"0f0e288895dea7effa6e916bd5fcca6fe6e96e94"},"previous_names":["omermecitoglu/next-openapi-json-generator"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omermecitoglu%2Fnext-openapi-json-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omermecitoglu%2Fnext-openapi-json-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omermecitoglu%2Fnext-openapi-json-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omermecitoglu%2Fnext-openapi-json-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omermecitoglu","download_url":"https://codeload.github.com/omermecitoglu/next-openapi-json-generator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242873730,"owners_count":20199291,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["generator","next","nextjs","openapi","openapi-json","self-documenting","swagger","swagger-json","ts","typescript"],"created_at":"2024-10-04T19:21:53.334Z","updated_at":"2026-01-03T07:00:50.968Z","avatar_url":"https://github.com/omermecitoglu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Next OpenAPI JSON Generator\n\n[![npm version](https://img.shields.io/npm/v/@omer-x/next-openapi-json-generator?logo=npm\u0026logoColor=CB3837\u0026color=CB3837)](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator)\n[![npm downloads](https://img.shields.io/npm/dm/@omer-x/next-openapi-json-generator?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA1MTIgNTEyIj48IS0tIUZvbnQgQXdlc29tZSBGcmVlIDYuNi4wIGJ5IEBmb250YXdlc29tZSAtIGh0dHBzOi8vZm9udGF3ZXNvbWUuY29tIExpY2Vuc2UgLSBodHRwczovL2ZvbnRhd2Vzb21lLmNvbS9saWNlbnNlL2ZyZWUgQ29weXJpZ2h0IDIwMjQgRm9udGljb25zLCBJbmMuLS0+PHBhdGggZD0iTTI4OCAzMmMwLTE3LjctMTQuMy0zMi0zMi0zMnMtMzIgMTQuMy0zMiAzMmwwIDI0Mi43LTczLjQtNzMuNGMtMTIuNS0xMi41LTMyLjgtMTIuNS00NS4zIDBzLTEyLjUgMzIuOCAwIDQ1LjNsMTI4IDEyOGMxMi41IDEyLjUgMzIuOCAxMi41IDQ1LjMgMGwxMjgtMTI4YzEyLjUtMTIuNSAxMi41LTMyLjggMC00NS4zcy0zMi44LTEyLjUtNDUuMyAwTDI4OCAyNzQuNyAyODggMzJ6TTY0IDM1MmMtMzUuMyAwLTY0IDI4LjctNjQgNjRsMCAzMmMwIDM1LjMgMjguNyA2NCA2NCA2NGwzODQgMGMzNS4zIDAgNjQtMjguNyA2NC02NGwwLTMyYzAtMzUuMy0yOC43LTY0LTY0LTY0bC0xMDEuNSAwLTQ1LjMgNDUuM2MtMjUgMjUtNjUuNSAyNS05MC41IDBMMTY1LjUgMzUyIDY0IDM1MnptMzY4IDU2YTI0IDI0IDAgMSAxIDAgNDggMjQgMjQgMCAxIDEgMC00OHoiIGZpbGw9IiMwMDc4MjAiIC8+PC9zdmc+\u0026color=007820)](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator)\n[![codecov](https://codecov.io/gh/omermecitoglu/next-openapi-json-generator/branch/main/graph/badge.svg)](https://codecov.io/gh/omermecitoglu/next-openapi-json-generator)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NDAgNTEyIj48IS0tIUZvbnQgQXdlc29tZSBGcmVlIDYuNi4wIGJ5IEBmb250YXdlc29tZSAtIGh0dHBzOi8vZm9udGF3ZXNvbWUuY29tIExpY2Vuc2UgLSBodHRwczovL2ZvbnRhd2Vzb21lLmNvbS9saWNlbnNlL2ZyZWUgQ29weXJpZ2h0IDIwMjQgRm9udGljb25zLCBJbmMuLS0+PHBhdGggZD0iTTM4NCAzMmwxMjggMGMxNy43IDAgMzIgMTQuMyAzMiAzMnMtMTQuMyAzMi0zMiAzMkwzOTguNCA5NmMtNS4yIDI1LjgtMjIuOSA0Ny4xLTQ2LjQgNTcuM0wzNTIgNDQ4bDE2MCAwYzE3LjcgMCAzMiAxNC4zIDMyIDMycy0xNC4zIDMyLTMyIDMybC0xOTIgMC0xOTIgMGMtMTcuNyAwLTMyLTE0LjMtMzItMzJzMTQuMy0zMiAzMi0zMmwxNjAgMCAwLTI5NC43Yy0yMy41LTEwLjMtNDEuMi0zMS42LTQ2LjQtNTcuM0wxMjggOTZjLTE3LjcgMC0zMi0xNC4zLTMyLTMyczE0LjMtMzIgMzItMzJsMTI4IDBjMTQuNi0xOS40IDM3LjgtMzIgNjQtMzJzNDkuNCAxMi42IDY0IDMyem01NS42IDI4OGwxNDQuOSAwTDUxMiAxOTUuOCA0MzkuNiAzMjB6TTUxMiA0MTZjLTYyLjkgMC0xMTUuMi0zNC0xMjYtNzguOWMtMi42LTExIDEtMjIuMyA2LjctMzIuMWw5NS4yLTE2My4yYzUtOC42IDE0LjItMTMuOCAyNC4xLTEzLjhzMTkuMSA1LjMgMjQuMSAxMy44bDk1LjIgMTYzLjJjNS43IDkuOCA5LjMgMjEuMSA2LjcgMzIuMUM2MjcuMiAzODIgNTc0LjkgNDE2IDUxMiA0MTZ6TTEyNi44IDE5NS44TDU0LjQgMzIwbDE0NC45IDBMMTI2LjggMTk1Ljh6TS45IDMzNy4xYy0yLjYtMTEgMS0yMi4zIDYuNy0zMi4xbDk1LjItMTYzLjJjNS04LjYgMTQuMi0xMy44IDI0LjEtMTMuOHMxOS4xIDUuMyAyNC4xIDEzLjhsOTUuMiAxNjMuMmM1LjcgOS44IDkuMyAyMS4xIDYuNyAzMi4xQzI0MiAzODIgMTg5LjcgNDE2IDEyNi44IDQxNlMxMS43IDM4MiAuOSAzMzcuMXoiIGZpbGw9IiNEMEE4MUMiIC8+PC9zdmc+)](https://opensource.org/licenses/MIT)\n[![GitHub last commit](https://img.shields.io/github/last-commit/omermecitoglu/next-openapi-json-generator?color=c977be\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NDAgNTEyIj48IS0tIUZvbnQgQXdlc29tZSBGcmVlIDYuNi4wIGJ5IEBmb250YXdlc29tZSAtIGh0dHBzOi8vZm9udGF3ZXNvbWUuY29tIExpY2Vuc2UgLSBodHRwczovL2ZvbnRhd2Vzb21lLmNvbS9saWNlbnNlL2ZyZWUgQ29weXJpZ2h0IDIwMjQgRm9udGljb25zLCBJbmMuLS0+PHBhdGggZD0iTTMyMCAzMzZhODAgODAgMCAxIDAgMC0xNjAgODAgODAgMCAxIDAgMCAxNjB6bTE1Ni44LTQ4QzQ2MiAzNjEgMzk3LjQgNDE2IDMyMCA0MTZzLTE0Mi01NS0xNTYuOC0xMjhMMzIgMjg4Yy0xNy43IDAtMzItMTQuMy0zMi0zMnMxNC4zLTMyIDMyLTMybDEzMS4yIDBDMTc4IDE1MSAyNDIuNiA5NiAzMjAgOTZzMTQyIDU1IDE1Ni44IDEyOEw2MDggMjI0YzE3LjcgMCAzMiAxNC4zIDMyIDMycy0xNC4zIDMyLTMyIDMybC0xMzEuMiAweiIgZmlsbD0iI0M5NzdCRSIgLz48L3N2Zz4=)](https://github.com/omermecitoglu/next-openapi-json-generator/commits/main/)\n[![GitHub issues](https://img.shields.io/github/issues/omermecitoglu/next-openapi-json-generator?color=a38eed\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiIgd2lkdGg9IjE2IiBoZWlnaHQ9IjE2Ij4KICA8cGF0aCBkPSJNOCA5LjVhMS41IDEuNSAwIDEgMCAwLTMgMS41IDEuNSAwIDAgMCAwIDNaIiBmaWxsPSIjQTM4RUVEIj48L3BhdGg+CiAgPHBhdGggZD0iTTggMGE4IDggMCAxIDEgMCAxNkE4IDggMCAwIDEgOCAwWk0xLjUgOGE2LjUgNi41IDAgMSAwIDEzIDAgNi41IDYuNSAwIDAgMC0xMyAwWiIgZmlsbD0iI0EzOEVFRCI+PC9wYXRoPgo8L3N2Zz4=)](https://github.com/omermecitoglu/next-openapi-json-generator/issues)\n[![GitHub stars](https://img.shields.io/github/stars/omermecitoglu/next-openapi-json-generator?style=social)](https://github.com/omermecitoglu/next-openapi-json-generator)\n\n## Overview\n\n`Next OpenAPI JSON Generator` is an open-source Next.js plugin that extracts and generates OpenAPI JSON specifications from your route handlers defined using `@omer-x/next-openapi-route-handler`. It simplifies the process of generating and maintaining OpenAPI documentation by leveraging TypeScript and Zod schemas.\n\n**Key Features:**\n- **Automated OpenAPI Generation**: Automatically generates OpenAPI JSON specs from your route handlers.\n- **TypeScript Integration**: Seamlessly integrates with TypeScript for strong type-checking.\n- **Zod Schema Support**: Uses Zod schemas for validation and generates JSON schemas for OpenAPI.\n- **Next.js Compatibility**: Works seamlessly with Next.js and integrates with other server-side libraries.\n\n\u003e **Note:** This package works in conjunction with [`Next OpenAPI Route Handler`](https://www.npmjs.com/package/@omer-x/next-openapi-route-handler) to extract the generated OpenAPI JSON.\n\n## Requirements\n\nTo use `@omer-x/next-openapi-json-generator`, you'll need the following dependencies in your Next.js project:\n\n- [TypeScript](https://www.typescriptlang.org/) \u003e= v5\n- [Next.js](https://nextjs.org/) \u003e= v13\n- [Zod](https://zod.dev/) \u003e= v3\n- [Next OpenAPI Route Handler](https://www.npmjs.com/package/@omer-x/next-openapi-route-handler)\n\n## Installation\n\nTo install this package, along with its peer dependency, run:\n\n```sh\nnpm install @omer-x/next-openapi-json-generator @omer-x/next-openapi-route-handler\n```\n\n## Usage\n\nThe `generateOpenApiSpec` function is used to extract and generate the OpenAPI JSON specification from your defined models. Here's a description of how to use it:\n\n### Example\n\n```typescript\nimport generateOpenApiSpec from \"@omer-x/next-openapi-json-generator\";\nimport { NewUserDTO, UserDTO, UserPatchDTO } from \"../models/user\";\n\nconst Page = async () =\u003e {\n const spec = await generateOpenApiSpec({\n UserDTO,\n NewUserDTO,\n UserPatchDTO,\n }, {\n // options\n });\n return \u003cReactSwagger spec={spec} /\u003e;\n};\n\nexport default Page;\n```\n\n### Parameters\n\nThe `generateOpenApiSpec` function takes an object with the following properties:\n\n| Property | Type | Description |\n| -------- | ------------------------------------------ | ---------------------------------------------------------------------------------- |\n| models | Record\u003cstring, [ZodType](https://zod.dev)\u003e | An object where keys are model names and values are Zod schemas |\n| options | Object | `(Optional)` An object to customize the functionality of the generator (see below) |\n\n#### Options\n\n| Property | Type | Description |\n| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| include | string[] | `(Optional)` An array of strings which specifies the routes will be included to the JSON output |\n| exclude | string[] | `(Optional)` An array of strings which specifies the routes will be excluded from the JSON output |\n| routeDefinerName | string | `(Optional)` Name of the function that was exported from the [`Next OpenAPI Route Handler`](https://www.npmjs.com/package/@omer-x/next-openapi-route-handler) (Default: `defineRoute`) |\n\n### Result\n\nThe function returns a promise that resolves to an OpenAPI JSON specification.\n\n```json\n{\n \"openapi\": \"3.1.0\",\n \"info\": {\n \"title\": \"User Service\",\n \"version\": \"1.0.0\"\n },\n \"paths\": {\n \"/users\": {\n \"get\": {\n ...\n },\n \"post\": {\n ...\n }\n },\n \"/users/{id}\": {\n \"get\": {\n \"operationId\": \"getUser\",\n \"summary\": \"Get a specific user by ID\",\n \"description\": \"Retrieve details of a specific user by their ID\",\n \"tags\": [\n \"Users\"\n ],\n \"parameters\": [\n {\n \"in\": \"path\",\n \"name\": \"id\",\n \"required\": true,\n \"description\": \"ID of the user\",\n \"schema\": {\n \"type\": \"string\",\n \"description\": \"ID of the user\"\n }\n }\n ],\n \"responses\": {\n \"200\": {\n \"description\": \"User details retrieved successfully\",\n \"content\": {\n \"application/json\": {\n \"schema\": {\n \"$ref\": \"#/components/schemas/UserDTO\"\n }\n }\n }\n },\n \"404\": {\n \"description\": \"User not found\"\n }\n }\n },\n \"patch\": {\n ...\n },\n \"delete\": {\n ...\n }\n }\n },\n \"components\": {\n \"schemas\": {\n \"UserDTO\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"format\": \"uuid\",\n \"description\": \"Unique identifier of the user\"\n },\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Display name of the user\"\n },\n \"email\": {\n \"type\": \"string\",\n \"description\": \"Email address of the user\"\n },\n \"password\": {\n \"type\": \"string\",\n \"maxLength\": 72,\n \"description\": \"Encrypted password of the user\"\n },\n \"createdAt\": {\n \"type\": \"string\",\n \"format\": \"date-time\",\n \"description\": \"Creation date of the user\"\n },\n \"updatedAt\": {\n \"type\": \"string\",\n \"format\": \"date-time\",\n \"description\": \"Modification date of the user\"\n }\n },\n \"required\": [\n \"id\",\n \"name\",\n \"email\",\n \"password\",\n \"createdAt\",\n \"updatedAt\"\n ],\n \"additionalProperties\": false,\n \"description\": \"Represents the data of a user in the system.\"\n },\n \"NewUserDTO\": {\n ...\n },\n \"UserPatchDTO\": {\n ...\n }\n }\n }\n}\n```\n\n[An example can be found here](https://github.com/omermecitoglu/example-user-service)\n\n## Screenshots\n\n| \u003ca href=\"https://i.imgur.com/ru3muBc.png\" target=\"_blank\"\u003e\u003cimg src=\"https://i.imgur.com/ru3muBc.png\" alt=\"screenshot-1\"\u003e\u003c/a\u003e | \u003ca href=\"https://i.imgur.com/utHaZ6X.png\" target=\"_blank\"\u003e\u003cimg src=\"https://i.imgur.com/utHaZ6X.png\" alt=\"screenshot-2\"\u003e\u003c/a\u003e | \u003ca href=\"https://i.imgur.com/2f24kPE.png\" target=\"_blank\"\u003e\u003cimg src=\"https://i.imgur.com/2f24kPE.png\" alt=\"screenshot-3\"\u003e\u003c/a\u003e | \u003ca href=\"https://i.imgur.com/z3KIJQ1.png\" target=\"_blank\"\u003e\u003cimg src=\"https://i.imgur.com/z3KIJQ1.png\" alt=\"screenshot-4\"\u003e\u003c/a\u003e |\n|:--------------:|:--------------:|:--------------:|:--------------:|\n| \u003ca href=\"https://i.imgur.com/IFKXOiX.png\" target=\"_blank\"\u003e\u003cimg src=\"https://i.imgur.com/IFKXOiX.png\" alt=\"screenshot-5\"\u003e\u003c/a\u003e | \u003ca href=\"https://i.imgur.com/xzVjAPq.png\" target=\"_blank\"\u003e\u003cimg src=\"https://i.imgur.com/xzVjAPq.png\" alt=\"screenshot-6\"\u003e\u003c/a\u003e | \u003ca href=\"https://i.imgur.com/HrWuHOR.png\" target=\"_blank\"\u003e\u003cimg src=\"https://i.imgur.com/HrWuHOR.png\" alt=\"screenshot-7\"\u003e\u003c/a\u003e | |\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomermecitoglu%2Fnext-openapi-json-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomermecitoglu%2Fnext-openapi-json-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomermecitoglu%2Fnext-openapi-json-generator/lists"}