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
to extract the generated OpenAPI JSON.
To use @omer-x/next-openapi-json-generator
, you'll need the following dependencies in your Next.js project:
- TypeScript >= v5
- Next.js >= v13
- Zod >= v3
- Next OpenAPI Route Handler
To install this package, along with its peer dependency, run:
npm install @omer-x/next-openapi-json-generator @omer-x/next-openapi-route-handler
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:
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 <ReactSwagger spec={spec} />;
};
export default Page;
The generateOpenApiSpec
function takes an object with the following properties:
Property | Type | Description |
---|---|---|
models | Record<string, ZodType> | 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) |
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 (Default: defineRoute ) |
The function returns a promise that resolves to an OpenAPI JSON specification.
{
"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": {
...
}
}
}
}
This project is licensed under the MIT License. See the LICENSE file for details.