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 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:

Installation

To install this package, along with its peer dependency, run:

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

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;

Parameters

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)

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` (Default: `defineRoute`)

Result

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": {
        ...
      }
    }
  }
}