@omer-x/next-openapi-json-generator

1.3.1 • Public • Published

Next OpenAPI JSON Generator

npm version npm downloads codecov License: MIT GitHub last commit GitHub issues GitHub stars

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

An example can be found here

Screenshots

screenshot-1 screenshot-2 screenshot-3 screenshot-4
screenshot-5 screenshot-6 screenshot-7

License

This project is licensed under the MIT License. See the LICENSE file for details.

Package Sidebar

Install

npm i @omer-x/next-openapi-json-generator

Weekly Downloads

182

Version

1.3.1

License

MIT

Unpacked Size

47.6 kB

Total Files

7

Last publish

Collaborators

  • omer-x