Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/omermecitoglu/next-openapi-json-generator
a Next.js plugin to generate OpenAPI documentation from route handlers
https://github.com/omermecitoglu/next-openapi-json-generator
generator next nextjs openapi openapi-json self-documenting swagger swagger-json ts typescript
Last synced: 21 days ago
JSON representation
a Next.js plugin to generate OpenAPI documentation from route handlers
- Host: GitHub
- URL: https://github.com/omermecitoglu/next-openapi-json-generator
- Owner: omermecitoglu
- License: mit
- Created: 2024-06-04T11:32:13.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-10-16T04:24:50.000Z (about 1 month ago)
- Last Synced: 2024-10-17T18:36:39.780Z (30 days ago)
- Topics: generator, next, nextjs, openapi, openapi-json, self-documenting, swagger, swagger-json, ts, typescript
- Language: TypeScript
- Homepage:
- Size: 224 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Next OpenAPI JSON Generator
[](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator)
[](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator)
[](https://codecov.io/gh/omermecitoglu/next-openapi-json-generator)
[](https://opensource.org/licenses/MIT)
[](https://github.com/omermecitoglu/next-openapi-json-generator/commits/main/)
[](https://github.com/omermecitoglu/next-openapi-json-generator/issues)
[](https://github.com/omermecitoglu/next-openapi-json-generator)
## Overview
`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.
**Key Features:**
- **Automated OpenAPI Generation**: Automatically generates OpenAPI JSON specs from your route handlers.
- **TypeScript Integration**: Seamlessly integrates with TypeScript for strong type-checking.
- **Zod Schema Support**: Uses Zod schemas for validation and generates JSON schemas for OpenAPI.
- **Next.js Compatibility**: Works seamlessly with Next.js and integrates with other server-side libraries.
> **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.
## Requirements
To use `@omer-x/next-openapi-json-generator`, you'll need the following dependencies in your Next.js project:
- [TypeScript](https://www.typescriptlang.org/) >= v5
- [Next.js](https://nextjs.org/) >= v13
- [Zod](https://zod.dev/) >= v3
- [Next OpenAPI Route Handler](https://www.npmjs.com/package/@omer-x/next-openapi-route-handler)
## Installation
To install this package, along with its peer dependency, run:
```sh
npm install @omer-x/next-openapi-json-generator @omer-x/next-openapi-route-handler
```
## Usage
The `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:
### Example
```typescript
import generateOpenApiSpec from "@omer-x/next-openapi-json-generator";
import { NewUserDTO, UserDTO, UserPatchDTO } from "../models/user";
const Page = async () => {
const spec = await generateOpenApiSpec({
UserDTO,
NewUserDTO,
UserPatchDTO,
}, {
// options
});
return ;
};
export default Page;
```
### Parameters
The `generateOpenApiSpec` function takes an object with the following properties:
| Property | Type | Description |
| -------- | ------------------------------------------ | ---------------------------------------------------------------------------------- |
| models | Record | An object where keys are model names and values are Zod schemas |
| options | Object | `(Optional)` An object to customize the functionality of the generator (see below) |
#### Options
| Property | Type | Description |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| include | string[] | `(Optional)` An array of strings which specifies the routes will be included to the JSON output |
| exclude | string[] | `(Optional)` An array of strings which specifies the routes will be excluded from the JSON output |
| 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`) |
### Result
The function returns a promise that resolves to an OpenAPI JSON specification.
```json
{
"openapi": "3.1.0",
"info": {
"title": "User Service",
"version": "1.0.0"
},
"paths": {
"/users": {
"get": {
...
},
"post": {
...
}
},
"/users/{id}": {
"get": {
"operationId": "getUser",
"summary": "Get a specific user by ID",
"description": "Retrieve details of a specific user by their ID",
"tags": [
"Users"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "ID of the user",
"schema": {
"type": "string",
"description": "ID of the user"
}
}
],
"responses": {
"200": {
"description": "User details retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserDTO"
}
}
}
},
"404": {
"description": "User not found"
}
}
},
"patch": {
...
},
"delete": {
...
}
}
},
"components": {
"schemas": {
"UserDTO": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier of the user"
},
"name": {
"type": "string",
"description": "Display name of the user"
},
"email": {
"type": "string",
"description": "Email address of the user"
},
"password": {
"type": "string",
"maxLength": 72,
"description": "Encrypted password of the user"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation date of the user"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Modification date of the user"
}
},
"required": [
"id",
"name",
"email",
"password",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "Represents the data of a user in the system."
},
"NewUserDTO": {
...
},
"UserPatchDTO": {
...
}
}
}
}
```
[An example can be found here](https://github.com/omermecitoglu/example-user-service)
## Screenshots
| 
| 
| 
| 
|
|:--------------:|:--------------:|:--------------:|:--------------:|
| 
| 
| 
| |
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.