### Install Next.js OpenAPI Route Handler and Generator Source: https://github.com/omermecitoglu/next-openapi-route-handler/blob/main/README.md This command installs the `@omer-x/next-openapi-route-handler` package along with its peer dependency `@omer-x/next-openapi-json-generator`, which is essential for extracting the generated OpenAPI JSON specifications. ```Shell npm install @omer-x/next-openapi-route-handler @omer-x/next-openapi-json-generator ``` -------------------------------- ### Generated OpenAPI Specification for User Service Source: https://github.com/omermecitoglu/next-openapi-route-handler/blob/main/README.md Illustrates the OpenAPI 3.1.0 JSON output generated from the `defineRoute` configuration. It details the `/users/{id}` GET endpoint, including its operation ID, summary, description, path parameters, and responses. It also shows the `UserDTO` schema definition within `components/schemas`. ```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": { ... } } } } ``` -------------------------------- ### Define Next.js API Route Handler for User Retrieval Source: https://github.com/omermecitoglu/next-openapi-route-handler/blob/main/README.md Demonstrates using `defineRoute` to create a GET endpoint for fetching user details by ID. It includes Zod schema for path parameters, asynchronous action for database interaction, custom response handling for success and not found cases, and a `handleErrors` function for different parsing error types. ```typescript import defineRoute from "@omer-x/next-openapi-route-handler"; import z from "zod"; export const { GET } = defineRoute({ operationId: "getUser", method: "GET", summary: "Get a specific user by ID", description: "Retrieve details of a specific user by their ID", tags: ["Users"], pathParams: z.object({ id: z.string().describe("ID of the user") }), action: async ({ pathParams }) => { const results = await db.select().from(users).where(eq(users.id, pathParams.id)); const user = results.shift(); if (!user) return new Response(null, { status: 404 }); return Response.json(user); }, responses: { 200: { description: "User details retrieved successfully", content: UserDTO }, 404: { description: "User not found" } }, // optional 👇👇👇 handleErrors: (errorType, issues) => { console.log(issues); switch (errorType) { "PARSE_FORM_DATA": "PARSE_REQUEST_BODY": "PARSE_SEARCH_PARAMS": return new Response(null, { status: 400 }); "PARSE_PATH_PARAMS": return new Response(null, { status: 404 }); "UNNECESSARY_PATH_PARAMS": "UNKNOWN_ERROR": return new Response(null, { status: 500 }); } } }); ``` -------------------------------- ### API Response Definition Properties Source: https://github.com/omermecitoglu/next-openapi-route-handler/blob/main/README.md Defines the properties used to specify a response within the OpenAPI route handler configuration, including description, content schema, and array indication. ```APIDOC Response Definition Properties: description: string - Description of the response. content: ZodType (Optional) - Zod schema for the response body. isArray: boolean (Optional) - Is the content an array? ``` -------------------------------- ### API Reference for defineRoute Function Parameters Source: https://github.com/omermecitoglu/next-openapi-route-handler/blob/main/README.md The `defineRoute` function is used to define route handlers in a type-safe and self-documenting manner. This section details the properties of its input parameter, covering operation metadata, request validation schemas, and response definitions. ```APIDOC defineRoute(options: object): operationId: string Unique identifier for the operation. method: string HTTP method for the route (e.g., GET, POST, PUT, PATCH, DELETE). summary: string Short summary of the operation. description: string Detailed description of the operation. tags: string[] Tags for categorizing the operation. pathParams: ZodType (Optional) Zod schema for validating path parameters. queryParams: ZodType (Optional) Zod schema for validating query parameters. requestBody: ZodType Zod schema for the request body (required for POST, PUT, PATCH). hasFormData: boolean Is the request body a FormData action: (source: ActionSource) => Promise Function handling the request, receiving pathParams, queryParams, and requestBody. responses: Record Object defining possible responses, each with a description and optional content schema. handleErrors: (errorType: string, issues?: ZodIssues[]) => Response (Optional) Custom error handler can be provided to replace the default behavior. ``` -------------------------------- ### API Reference for ActionSource Properties Source: https://github.com/omermecitoglu/next-openapi-route-handler/blob/main/README.md The `ActionSource` object is passed as an argument to the `action` function within `defineRoute`. It provides access to parsed request data, including validated path parameters, query parameters, and the request body, enabling the handler to process the incoming request. ```APIDOC ActionSource: pathParams: ZodType Parsed parameters from the request URL path. queryParams: ZodType Parsed parameters from the request query. body: ZodType Parsed request body. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.