hono-openapi-better-response

hono-openapi-better-response is a TypeScript utility library for building OpenAPI response objects for hono-openapi.

Current version: 1.0.0.

It provides:

• A generic OpenApiResponse function for any status code.
• A generic OpenApiResponses function to merge multiple response objects.
• A large set of prebuilt helpers such as OpenApiOkResponse, OpenApiBadRequestResponse, and OpenApiInternalServerErrorResponse.
• Standard Schema integration through hono-openapi's resolver(schema).

Installation

Install the package with your preferred package manager:

npm install hono-openapi-better-response

pnpm add hono-openapi-better-response

yarn add hono-openapi-better-response

bun add hono-openapi-better-response

hono-openapi-better-response expects these peer dependencies:

• hono-openapi
• openapi-types
• typescript

Build (for contributors)

This project uses Bun + tsdown.

bun install
bun run build

Usage

1) Generic function

import { OpenApiResponse } from 'hono-openapi-better-response'

const responses = OpenApiResponse(200, 'Success')
// => { 200: { description: 'Success' } }

2) Status helper

import { OpenApiCreatedResponse } from 'hono-openapi-better-response'

const responses = OpenApiCreatedResponse('Resource created')
// => { 201: { description: 'Resource created' } }

3) With schema (hono-openapi resolver)

If a Standard Schema-compatible object is provided, the library adds:

• content['application/json'].schema = resolver(schema)

import { OpenApiOkResponse } from 'hono-openapi-better-response'
import { z } from 'zod'

const userSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
})

const responses = OpenApiOkResponse('User fetched', userSchema)

4) Merge multiple responses

Use OpenApiResponses to combine multiple response objects into one:

import {
  OpenApiOkResponse,
  OpenApiBadRequestResponse,
  OpenApiResponses,
} from 'hono-openapi-better-response'

const responses = OpenApiResponses(
  OpenApiOkResponse('Success'),
  OpenApiBadRequestResponse('Invalid request'),
)

API

OpenApiResponse(code: number, description: string, schema?) => Record<string, OpenAPIV3_1.ResponseObject | OpenAPIV3_1.ReferenceObject>
OpenApiResponses(...responses: Array<Record<string, OpenAPIV3_1.ResponseObject | OpenAPIV3_1.ReferenceObject>>) => Record<string, OpenAPIV3_1.ResponseObject | OpenAPIV3_1.ReferenceObject>

• code: HTTP status code.
• description: OpenAPI response description.
• schema (optional): a Standard Schema-compatible schema that can be consumed by hono-openapi resolver.
• responses: one or more response objects to merge; later entries override earlier keys when status codes collide.

Exported Helper Families

The package exports helpers for many HTTP status codes:

• 1xx: OpenApiContinueResponse, OpenApiSwitchingProtocolsResponse, ...
• 2xx: OpenApiOkResponse, OpenApiCreatedResponse, OpenApiNoContentResponse, ...
• 3xx: OpenApiMovedPermanentlyResponse, OpenApiTemporaryRedirectResponse, ...
• 4xx: OpenApiBadRequestResponse, OpenApiUnauthorizedResponse, OpenApiNotFoundResponse, ...
• 5xx: OpenApiInternalServerErrorResponse, OpenApiBadGatewayResponse, OpenApiServiceUnavailableResponse, ...

All helpers share the same signature:

(description: string, schema?) => Record<string, OpenAPIV3_1.ResponseObject | OpenAPIV3_1.ReferenceObject>

Type Notes

• The library uses openapi-types types (OpenAPIV3_1).
• It accepts Standard Schema-compatible inputs and delegates schema conversion to hono-openapi.
• It is authored in TypeScript and ships both ESM and CJS builds.