zod-openapi-share

!GitHub Release
!NPM Type Definitions
!GitHub License
!Vitest
!Typedoc

zod-openapi-share is an extension package for @hono/zod-openapi that lets you centralize and reuse response definitions across endpoints.
Normally, @hono/zod-openapi requires you to redefine the same responses (e.g., error schemas) for every endpoint, but with zod-openapi-share, you can avoid repetition and prevent definition drift, making your backend development using hono + @hono/zod-openapi cleaner and more consistent.

> [!IMPORTANT]
> Be sure to use the latest version.

What is zod-openapi-share?

In projects using hono, you may have opportunities to use a convenient package called @hono/zod-openapi as middleware for generating OpenAPI schemas.
This package allows you to define both OpenAPI schemas and Zod-based validation at the same time.

However, it has a major drawback: you must repeatedly write out the responses definitions for every single status code across all endpoints.
In many cases, error responses share the exact same structure across endpoints — yet, even if they are identical, you still have to duplicate those definitions.

To solve this, zod-openapi-share provides a way to centralize and reuse response definitions by wrapping around @hono/zod-openapi.
Think of zod-openapi-share as an extension package for @hono/zod-openapi.
When using it, you’ll need three packages together: hono, @hono/zod-openapi, and zod-openapi-share.

By unifying response definitions, you can develop without worrying about unintended inconsistencies between endpoints.
If you’re using hono and @hono/zod-openapi, be sure to try zod-openapi-share!

How to Use

Examples Here

- cloudflare workers example
- https://github.com/Myxogastria0808/zod-openapi-share/tree/main/examples/cloudflare-workers/

- nodejs example
- https://github.com/Myxogastria0808/zod-openapi-share/tree/main/examples/nodejs/

1. Install Packages

`sh
npm install hono @hono/zod-openapi zod-openapi-share
`

2. Create Zod Schema and ZodOpenAPISchema Class Instance

- Example

https://github.com/Myxogastria0808/zod-openapi-share/tree/main/examples/nodejs/src/app/share.ts

`ts
import { z } from '@hono/zod-openapi';
import { ZodOpenAPISchema } from 'zod-openapi-share';

const ContentlyStatusCodeArray = [
100, 102, 103, 200, 201, 202, 203, 206, 207, 208, 226, 300, 301, 302, 303, 305, 306, 307, 308, 400, 401, 402, 403,
404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 421, 422, 423, 424, 425, 426, 428, 429,
431, 451, 500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511, -1,
] as const;

// Zod Schema for Error Response
export const errorResponseSchema = z.object({
status: z.union(ContentlyStatusCodeArray.map((code) => z.literal(code))).meta({
example: 400,
description: 'HTTP Status Code',
}),
message: z.string().min(1).meta({
example: 'Bad Request',
description: 'Error Message',
}),
});

export type ErrorResponseSchemaType = z.infer;

// ZodOpenAPISchema Instance
/**
* Define Shared Responses Here
*/
export const route = new ZodOpenAPISchema({
400: {
description: 'Bad Request',
content: { 'application/json': { schema: errorResponseSchema } },
},
500: {
description: 'Internal Server Error',
content: { 'application/json': { schema: errorResponseSchema } },
},
} as const);

`

3. Create RouteConfig Type Object

- createSchema Method

When you want to learn how to use createRoute,
please refer to the @hono/zod-openapi.

`ts
zodOpenAPISchemaInstance.createSchema(
createRoute object (@hono/zod-openapi RouteConfig type object),
StatusCode[] (Array of status codes to be shared from ZodOpenAPISchema instance)
);
`

- Example

https://github.com/Myxogastria0808/zod-openapi-share/tree/main/examples/nodejs/src/app/route.ts

`ts
import { z } from '@hono/zod-openapi';
import { route } from './share.js';

const responseBodySchema = z.object({
result: z.string().meta({
example: 'Hello World!',
description: 'Sample Endpoint Response',
}),
});

export const rootRoute = route.createSchema(
{
path: '/',
method: 'get',
description: 'Sample Endpoint',
responses: {
200: {
description: 'OK',
content: {
'application/json': {
schema: responseBodySchema,
},
},
},
},
},
[400, 500]
);

`

4. Insert root Variable Into Hono app Instance

- Example

https://github.com/Myxogastria0808/zod-openapi-share/tree/main/examples/nodejs/src/app/index.ts

`typescript
import { OpenAPIHono } from '@hono/zod-openapi';
import { cors } from 'hono/cors';
import { HTTPException } from 'hono/http-exception';
import { type ErrorResponseSchemaType } from './share.js';
import { rootRoute } from './route.js';
import { Scalar } from '@scalar/hono-api-reference';

export const api = () => {
const app = new OpenAPIHono({
// Zod Validation Error Hook
defaultHook: (result) => {
if (!result.success) {
console.error(result.error);
throw new HTTPException(400, {
message: 'Zod Validation Error',
});
}
},
});

// 404 Not Found Handler
app.notFound((c) => {
console.error(Not Found: ${c.req.url});
return c.json({ status: 404, message: 'Not Found' } satisfies ErrorResponseSchemaType, 404);
});
// Other Error Handler
app.onError((error, c) => {
if (error instanceof HTTPException) {
return c.json(
{
status: error.status,
message: error.message,
} satisfies ErrorResponseSchemaType,
error.status
);
}
return c.json(
{
status: 500,
message: 'Internal Server Error',
} satisfies ErrorResponseSchemaType,
500
);
});

// Settings of CORS
app.use('*', cors());

// OpenAPI Document Endpoint
app.doc('/openapi', {
openapi: '3.1.0',
info: {
title: 'Echo API',
version: '1.0.0',
description: 'An example of OpenAPI with hono, @hono/zod-openapi, and zod-openapi-share.',
},
});

// Scalar Web UI Endpoint
// References
// https://guides.scalar.com/scalar/scalar-api-references/integrations/hono
app.get('/scalar', Scalar({ url: '/openapi' }));

/**
* Add route to app instance
*/
app.openapi(rootRoute, (c) => {
return c.json({ result: 'Hello World!' });
});

return app;
};

`

5. Define serve (Define Entry Point)

- Example

https://github.com/Myxogastria0808/zod-openapi-share/tree/main/examples/nodejs/src/index.ts

`ts
import { serve } from '@hono/node-server';
import { api } from './app/index.js';

serve(
{
fetch: api().fetch,
port: 3000,
},
(info) => {
console.log(Server is running on http://localhost:${info.port});
}
);

`

6. Define Generate OpenAPI Document Program

- Example

https://github.com/Myxogastria0808/zod-openapi-share/tree/main/examples/nodejs/src/openapi.ts

`ts
import { api } from './app/index.js';
import fs from 'node:fs';

const docs = api().getOpenAPI31Document({
openapi: '3.1.0',
info: {
title: 'hono + @hono/zod-openapi + zod-openapi-share sample',
version: '1.0.0',
description: 'This is a sample project to generate OpenAPI documents with Hono and Zod.',
},
});

const json = JSON.stringify(docs, null, 2);

fs.writeFileSync('./openapi.json', json);
console.log(json);

`

7. Add generate openapi.json scripts to package.json

- Example

`jsonc
{
"name": "example",
"type": "module",
"private": true,
"scripts": {
"dev": "tsx watch src/index.ts",
"build": "tsc",
"start": "node dist/index.js",
"openapi": "tsx src/openapi.ts" // Add this script for generating OpenAPI document
},
// [Omitted]
}
``

HTML Documentation Generated by typedoc

https://myxogastria0808.github.io/zod-openapi-share/

Test Coverage Generated by @vitest/coverage-v8

https://myxogastria0808.github.io/zod-openapi-share/coverage/

Test Result Generated by @vitest/ui

https://myxogastria0808.github.io/zod-openapi-share/html/

DeepWiki

> [!WARNING]
> The accuracy of the contents of generated deepwiki has not been verified by me.
>
> I recommend that you look at the documentation at typedoc.

https://deepwiki.com/Myxogastria0808/zod-openapi-share/