@hono/zod-openapi 0.18.3 → 0.19.0

package/README.md

@@ -52,6 +52,7 @@ const UserSchema = z
 ```
 
 > [!TIP]
+>
 > `UserSchema` schema will be registered as `"#/components/schemas/User"` refs in the OpenAPI document.
 > If you want to register the schema as referenced components, use `.openapi()` method.
 
@@ -114,6 +115,71 @@ You can start your app just like you would with Hono. For Cloudflare Workers and
 export default app
 ```
 
+> [!IMPORTANT]
+> The request must have the proper `Content-Type` to ensure the validation. For example, if you want to validate a JSON body, the request must have the `Content-Type` to `application/json` in the request. Otherwise, the value of `c.req.valid('json')` will be `{}`.
+>
+> ```ts
+> import { createRoute, z, OpenAPIHono } from '@hono/zod-openapi'
+>
+> const route = createRoute({
+>   method: 'post',
+>   path: '/books',
+>   request: {
+>     body: {
+>       content: {
+>         'application/json': {
+>           schema: z.object({
+>             title: z.string(),
+>           }),
+>         },
+>       },
+>     },
+>   },
+>   responses: {
+>     200: {
+>       description: 'Success message',
+>     },
+>   },
+> })
+>
+> const app = new OpenAPIHono()
+>
+> app.openapi(route, (c) => {
+>   const validatedBody = c.req.valid('json')
+>   return c.json(validatedBody) // validatedBody is {}
+> })
+>
+> const res = await app.request('/books', {
+>   method: 'POST',
+>   body: JSON.stringify({ title: 'foo' }),
+>   // The Content-Type header is lacking.
+> })
+>
+> const data = await res.json()
+> console.log(data) // {}
+> ```
+>
+> If you want to force validation of requests that do not have the proper `Content-Type`, set the value of `request.body.required` to `true`.
+>
+> ```ts
+> const route = createRoute({
+>   method: 'post',
+>   path: '/books',
+>   request: {
+>     body: {
+>       content: {
+>         'application/json': {
+>           schema: z.object({
+>             title: z.string(),
+>           }),
+>         },
+>       },
+>       required: true, // <== add
+>     },
+>   },
+> })
+> ```
+
 ### Handling Validation Errors
 
 Validation errors can be handled as follows:
@@ -241,7 +307,10 @@ You can generate OpenAPI v3.1 spec using the following methods:
 
 ```ts
 app.doc31('/docs', { openapi: '3.1.0', info: { title: 'foo', version: '1' } }) // new endpoint
-app.getOpenAPI31Document({ openapi: '3.1.0', info: { title: 'foo', version: '1' } }) // schema object
+app.getOpenAPI31Document({
+  openapi: '3.1.0',
+  info: { title: 'foo', version: '1' },
+}) // schema object
 ```
 
 ### The Registry
@@ -285,10 +354,7 @@ const route = createRoute({
   request: {
     params: ParamsSchema,
   },
-  middleware: [
-    prettyJSON(),
-    cache({ cacheName: 'my-cache' })
-  ] as const, // Use `as const` to ensure TypeScript infers the middleware's Context.
+  middleware: [prettyJSON(), cache({ cacheName: 'my-cache' })] as const, // Use `as const` to ensure TypeScript infers the middleware's Context.
   responses: {
     200: {
       content: {
@@ -385,6 +451,17 @@ app.doc('/doc', (c) => ({
 }))
 ```
 
+### How to exclude a specific route from OpenAPI docs
+
+You can use `hide` property as follows:
+
+```ts
+const route = createRoute({
+  // ...
+  hide: true,
+})
+```
+
 ## Limitations
 
 ### Combining with `Hono`

package/dist/index.d.mts

@@ -4,14 +4,15 @@ import { RouteConfig as RouteConfig$1, ZodMediaTypeObject, OpenAPIRegistry, ZodR
 export { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
 import { MiddlewareHandler, TypedResponse, Env, ValidationTargets, Context, Input, Handler, Schema, Hono, ToSchema } from 'hono';
 import { MergePath, MergeSchemaPath } from 'hono/types';
-import { RemoveBlankRecord, SimplifyDeepArray, JSONValue, JSONParsed } from 'hono/utils/types';
 import { StatusCode, InfoStatusCode, SuccessStatusCode, RedirectStatusCode, ClientErrorStatusCode, ServerErrorStatusCode } from 'hono/utils/http-status';
+import { RemoveBlankRecord, SimplifyDeepArray, JSONValue, JSONParsed } from 'hono/utils/types';
 import { ZodError, ZodType, z, ZodSchema } from 'zod';
 export { z } from 'zod';
 
 type MaybePromise<T> = Promise<T> | T;
 type RouteConfig = RouteConfig$1 & {
     middleware?: MiddlewareHandler | MiddlewareHandler[];
+    hide?: boolean;
 };
 type RequestTypes = {
     body?: ZodRequestBody;
@@ -169,7 +170,7 @@ declare class OpenAPIHono<E extends Env = Env, S extends Schema = {}, BasePath e
      *  }
      *)
      */
-    openapi: <R extends RouteConfig, I extends Input = InputTypeBase<R, "params", "param"> & InputTypeBase<R, "query", "query"> & InputTypeBase<R, "headers", "header"> & InputTypeBase<R, "cookies", "cookie"> & InputTypeForm<R> & InputTypeJson<R>, P extends string = ConvertPathType<R["path"]>>({ middleware: routeMiddleware, ...route }: R, handler: Handler<R['middleware'] extends MiddlewareHandler[] | MiddlewareHandler ? RouteMiddlewareParams<R>['env'] & E : E, P, I, R extends {
+    openapi: <R extends RouteConfig, I extends Input = InputTypeBase<R, "params", "param"> & InputTypeBase<R, "query", "query"> & InputTypeBase<R, "headers", "header"> & InputTypeBase<R, "cookies", "cookie"> & InputTypeForm<R> & InputTypeJson<R>, P extends string = ConvertPathType<R["path"]>>({ middleware: routeMiddleware, hide, ...route }: R, handler: Handler<R['middleware'] extends MiddlewareHandler[] | MiddlewareHandler ? RouteMiddlewareParams<R>['env'] & E : E, P, I, R extends {
         responses: {
             [statusCode: number]: {
                 content: {

package/dist/index.d.ts

@@ -4,14 +4,15 @@ import { RouteConfig as RouteConfig$1, ZodMediaTypeObject, OpenAPIRegistry, ZodR
 export { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
 import { MiddlewareHandler, TypedResponse, Env, ValidationTargets, Context, Input, Handler, Schema, Hono, ToSchema } from 'hono';
 import { MergePath, MergeSchemaPath } from 'hono/types';
-import { RemoveBlankRecord, SimplifyDeepArray, JSONValue, JSONParsed } from 'hono/utils/types';
 import { StatusCode, InfoStatusCode, SuccessStatusCode, RedirectStatusCode, ClientErrorStatusCode, ServerErrorStatusCode } from 'hono/utils/http-status';
+import { RemoveBlankRecord, SimplifyDeepArray, JSONValue, JSONParsed } from 'hono/utils/types';
 import { ZodError, ZodType, z, ZodSchema } from 'zod';
 export { z } from 'zod';
 
 type MaybePromise<T> = Promise<T> | T;
 type RouteConfig = RouteConfig$1 & {
     middleware?: MiddlewareHandler | MiddlewareHandler[];
+    hide?: boolean;
 };
 type RequestTypes = {
     body?: ZodRequestBody;
@@ -169,7 +170,7 @@ declare class OpenAPIHono<E extends Env = Env, S extends Schema = {}, BasePath e
      *  }
      *)
      */
-    openapi: <R extends RouteConfig, I extends Input = InputTypeBase<R, "params", "param"> & InputTypeBase<R, "query", "query"> & InputTypeBase<R, "headers", "header"> & InputTypeBase<R, "cookies", "cookie"> & InputTypeForm<R> & InputTypeJson<R>, P extends string = ConvertPathType<R["path"]>>({ middleware: routeMiddleware, ...route }: R, handler: Handler<R['middleware'] extends MiddlewareHandler[] | MiddlewareHandler ? RouteMiddlewareParams<R>['env'] & E : E, P, I, R extends {
+    openapi: <R extends RouteConfig, I extends Input = InputTypeBase<R, "params", "param"> & InputTypeBase<R, "query", "query"> & InputTypeBase<R, "headers", "header"> & InputTypeBase<R, "cookies", "cookie"> & InputTypeForm<R> & InputTypeJson<R>, P extends string = ConvertPathType<R["path"]>>({ middleware: routeMiddleware, hide, ...route }: R, handler: Handler<R['middleware'] extends MiddlewareHandler[] | MiddlewareHandler ? RouteMiddlewareParams<R>['env'] & E : E, P, I, R extends {
         responses: {
             [statusCode: number]: {
                 content: {

package/dist/index.js

@@ -70,8 +70,10 @@ var OpenAPIHono = class _OpenAPIHono extends import_hono.Hono {
    *  }
    *)
    */
-  openapi = ({ middleware: routeMiddleware, ...route }, handler, hook = this.defaultHook) => {
-    this.openAPIRegistry.registerPath(route);
+  openapi = ({ middleware: routeMiddleware, hide, ...route }, handler, hook = this.defaultHook) => {
+    if (!hide) {
+      this.openAPIRegistry.registerPath(route);
+    }
     const validators = [];
     if (route.request?.query) {
       const validator = (0, import_zod_validator.zValidator)("query", route.request.query, hook);
@@ -190,12 +192,22 @@ var OpenAPIHono = class _OpenAPIHono extends import_hono.Hono {
         case "route":
           return this.openAPIRegistry.registerPath({
             ...def.route,
-            path: (0, import_url.mergePath)(pathForOpenAPI, def.route.path)
+            path: (0, import_url.mergePath)(
+              pathForOpenAPI,
+              // @ts-expect-error _basePath is private
+              app._basePath,
+              def.route.path
+            )
           });
         case "webhook":
           return this.openAPIRegistry.registerWebhook({
             ...def.webhook,
-            path: (0, import_url.mergePath)(pathForOpenAPI, def.webhook.path)
+            path: (0, import_url.mergePath)(
+              pathForOpenAPI,
+              // @ts-expect-error _basePath is private
+              app._basePath,
+              def.webhook.path
+            )
           });
         case "schema":
           return this.openAPIRegistry.register(def.schema._def.openapi._internal.refId, def.schema);

package/dist/index.mjs

@@ -48,8 +48,10 @@ var OpenAPIHono = class _OpenAPIHono extends Hono {
    *  }
    *)
    */
-  openapi = ({ middleware: routeMiddleware, ...route }, handler, hook = this.defaultHook) => {
-    this.openAPIRegistry.registerPath(route);
+  openapi = ({ middleware: routeMiddleware, hide, ...route }, handler, hook = this.defaultHook) => {
+    if (!hide) {
+      this.openAPIRegistry.registerPath(route);
+    }
     const validators = [];
     if (route.request?.query) {
       const validator = zValidator("query", route.request.query, hook);
@@ -168,12 +170,22 @@ var OpenAPIHono = class _OpenAPIHono extends Hono {
         case "route":
           return this.openAPIRegistry.registerPath({
             ...def.route,
-            path: mergePath(pathForOpenAPI, def.route.path)
+            path: mergePath(
+              pathForOpenAPI,
+              // @ts-expect-error _basePath is private
+              app._basePath,
+              def.route.path
+            )
           });
         case "webhook":
           return this.openAPIRegistry.registerWebhook({
             ...def.webhook,
-            path: mergePath(pathForOpenAPI, def.webhook.path)
+            path: mergePath(
+              pathForOpenAPI,
+              // @ts-expect-error _basePath is private
+              app._basePath,
+              def.webhook.path
+            )
           });
         case "schema":
           return this.openAPIRegistry.register(def.schema._def.openapi._internal.refId, def.schema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hono/zod-openapi",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "description": "A wrapper class of Hono which supports OpenAPI.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",