@hono/zod-openapi 0.0.1 → 0.1.1

package/README.md

@@ -1,22 +1,29 @@
 # Zod OpenAPI Hono
 
-A wrapper class for Hono that supports OpenAPI. With it, you can validate values and types using [Zod](https://zod.dev/) and generate OpenAPI Swagger documentation.
-This is based on [Zod to OpenAPI](https://github.com/asteasolutions/zod-to-openapi).
-For details on creating schemas and defining routes, please refer to this resource.
+**Zod OpenAPI Hono** is an extended Hono class that supports OpenAPI. With it, you can validate values and types using [**Zod**](https://zod.dev/) and generate OpenAPI Swagger documentation. This is based on [**Zod to OpenAPI**](https://github.com/asteasolutions/zod-to-openapi) (thanks a lot!). For details on creating schemas and defining routes, please refer to [the "Zod to OpenAPI" resource](https://github.com/asteasolutions/zod-to-openapi).
 
-_This is not a middleware but hosted on this monorepo_
+_Note: This is not standalone middleware but is hosted on the monorepo "[github.com/honojs/middleware](https://github.com/honojs/middleware)"._
+
+## Limitations
+
+- Currently, it does not support validation of _headers_ and _cookies_.
+- An instance of Zod OpenAPI Hono cannot be used as a "subApp" in conjunction with `rootApp.route('/api', subApp)`.
 
 ## Usage
 
-### Install
+### Installation
 
-```
+You can install it via npm. It should be installed alongside `hono` and `zod`.
+
+```sh
 npm i hono zod @hono/zod-openapi
 ```
 
-### Write your application
+### Basic Usage
+
+#### Setting up your application
 
-Define schemas:
+First, define your schemas with Zod. The `z` object should be imported from `@hono/zod-openapi`:
 
 ```ts
 import { z } from '@hono/zod-openapi'
@@ -36,8 +43,8 @@ const ParamsSchema = z.object({
 
 const UserSchema = z
   .object({
-    id: z.number().openapi({
-      example: 123,
+    id: z.string().openapi({
+      example: '123',
     }),
     name: z.string().openapi({
       example: 'John Doe',
@@ -49,7 +56,7 @@ const UserSchema = z
   .openapi('User')
 ```
 
-Create routes:
+Next, create a route:
 
 ```ts
 import { createRoute } from '@hono/zod-openapi'
@@ -67,27 +74,86 @@ const route = createRoute({
           schema: UserSchema,
         },
       },
-      description: 'Get the user',
+      description: 'Retrieve the user',
     },
+  },
+})
+```
+
+Finally, set up the app:
+
+```ts
+import { OpenAPIHono } from '@hono/zod-openapi'
+
+const app = new OpenAPIHono()
+
+app.openapi(route, (c) => {
+  const { id } = c.req.valid('param')
+  return c.jsonT({
+    id,
+    age: 20,
+    name: 'Ultra-man',
+  })
+})
+
+// The OpenAPI documentation will be available at /doc
+app.doc('/doc', {
+  openapi: '3.0.0',
+  info: {
+    version: '1.0.0',
+    title: 'My API',
+  },
+})
+```
+
+You can start your app just like you would with Hono. For Cloudflare Workers and Bun, use this entry point:
+
+```ts
+export default app
+```
+
+### Handling Validation Errors
+
+Validation errors can be handled as follows:
+
+First, define the error schema:
+
+```ts
+const ErrorSchema = z.object({
+  code: z.number().openapi({
+    example: 400,
+  }),
+  message: z.string().openapi({
+    example: 'Bad Request',
+  }),
+})
+```
+
+Then, add the error response:
+
+```ts
+const route = createRoute({
+  method: 'get',
+  path: '/users/:id',
+  request: {
+    params: ParamsSchema,
+  },
+  responses: {
     400: {
       content: {
         'application/json': {
           schema: ErrorSchema,
         },
       },
-      description: 'Error!',
+      description: 'Returns an error',
     },
   },
 })
 ```
 
-Create the App:
+Finally, add the hook:
 
 ```ts
-import { OpenAPIHono } from '@hono/zod-openapi'
-
-const app = new OpenAPIHono()
-
 app.openapi(
   route,
   (c) => {
@@ -98,31 +164,60 @@ app.openapi(
       name: 'Ultra-man',
     })
   },
+  // Hook
   (result, c) => {
     if (!result.success) {
-      const res = c.jsonT(
+      return c.jsonT(
         {
-          ok: false,
+          code: 400,
+          message: 'Validation Error',
         },
         400
       )
-      return res
     }
   }
 )
+```
 
-app.doc('/doc', {
-  openapi: '3.0.0',
-  info: {
-    version: '1.0.0',
-    title: 'My API',
-  },
+### Middleware
+
+Zod OpenAPI Hono is an extension of Hono, so you can use Hono's middleware in the same way:
+
+```ts
+import { prettyJSON } from 'hono/pretty-json'
+
+//...
+
+app.use('/doc/*', prettyJSON())
+```
+
+### RPC Mode
+
+Zod OpenAPI Hono supports Hono's RPC mode. You can define types for the Hono Client as follows:
+
+```ts
+import { hc } from 'hono/client'
+
+const appRoutes = app.openapi(route, (c) => {
+  const data = c.req.valid('json')
+  return c.jsonT({
+    id: data.id,
+    message: 'Success',
+  })
 })
+
+const client = hc<typeof appRoutes>('http://localhost:8787/')
 ```
 
-## Author
+## References
+
+- [Hono](https://hono.dev/)
+- [Zod](https://zod.dev/)
+- [Zod to OpenAPI](https://github.com/asteasolutions/zod-to-openapi)
+
+## Authors
 
-Yusuke Wada <https://github.com/yusukebe>
+- Yusuke Wada <https://github.com/yusukebe>
 
 ## License
 

package/dist/index.cjs

@@ -83,7 +83,7 @@ var OpenAPIHono = class extends import_hono.Hono {
           }
         }
       }
-      this.on([route.method], route.path, ...validators, handler);
+      this.on([route.method], route.path.replace(/\/{(.+)}/, "/:$1"), ...validators, handler);
       return this;
     };
     this.getOpenAPIDocument = (config) => {

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as openapi3_ts_oas30 from 'openapi3-ts/oas30';
 import { RouteConfig, ZodRequestBody, ZodContentObject, ResponseConfig } from '@asteasolutions/zod-to-openapi';
 import { OpenAPIObjectConfig } from '@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator';
-import { Env, Hono, Input, Handler, Context, TypedResponse } from 'hono';
+import { Env, Hono, Input, Handler, Schema, Context, TypedResponse } from 'hono';
 import { AnyZodObject, z, ZodSchema, ZodError, ZodType } from 'zod';
 export { z } from 'zod';
 
@@ -14,18 +14,27 @@ type RequestTypes = {
 };
 type IsJson<T> = T extends string ? T extends `application/json${infer _Rest}` ? 'json' : never : never;
 type IsForm<T> = T extends string ? T extends `multipart/form-data${infer _Rest}` | `application/x-www-form-urlencoded${infer _Rest}` ? 'form' : never : never;
-type RequestPart<R extends RouteConfig, Part extends string> = Part extends keyof R['request'] ? R['request'][Part] : never;
+type RequestPart<R extends RouteConfig, Part extends string> = Part extends keyof R['request'] ? R['request'][Part] : {};
 type InputTypeBase<R extends RouteConfig, Part extends string, Type extends string> = R['request'] extends RequestTypes ? RequestPart<R, Part> extends AnyZodObject ? {
+    in: {
+        [K in Type]: z.input<RequestPart<R, Part>>;
+    };
     out: {
         [K in Type]: z.input<RequestPart<R, Part>>;
     };
 } : {} : {};
 type InputTypeJson<R extends RouteConfig> = R['request'] extends RequestTypes ? R['request']['body'] extends ZodRequestBody ? R['request']['body']['content'] extends ZodContentObject ? IsJson<keyof R['request']['body']['content']> extends never ? {} : R['request']['body']['content'][keyof R['request']['body']['content']]['schema'] extends ZodSchema<any> ? {
+    in: {
+        json: z.input<R['request']['body']['content'][keyof R['request']['body']['content']]['schema']>;
+    };
     out: {
         json: z.input<R['request']['body']['content'][keyof R['request']['body']['content']]['schema']>;
     };
 } : {} : {} : {} : {};
 type InputTypeForm<R extends RouteConfig> = R['request'] extends RequestTypes ? R['request']['body'] extends ZodRequestBody ? R['request']['body']['content'] extends ZodContentObject ? IsForm<keyof R['request']['body']['content']> extends never ? {} : R['request']['body']['content'][keyof R['request']['body']['content']]['schema'] extends ZodSchema<any> ? {
+    in: {
+        form: z.input<R['request']['body']['content'][keyof R['request']['body']['content']]['schema']>;
+    };
     out: {
         form: z.input<R['request']['body']['content'][keyof R['request']['body']['content']]['schema']>;
     };
@@ -38,10 +47,11 @@ type Hook<T, E extends Env, P extends string, O> = (result: {
     success: false;
     error: ZodError;
 }, c: Context<E, P>) => TypedResponse<O> | Promise<TypedResponse<T>> | void;
+type ConvertPathType<T extends string> = T extends `${infer _}/{${infer Param}}${infer _}` ? `/:${Param}` : T;
 declare class OpenAPIHono<E extends Env = Env, S = {}, BasePath extends string = '/'> extends Hono<E, S, BasePath> {
     #private;
     constructor();
-    openapi: <R extends RouteConfig, I extends Input = InputTypeBase<R, "params", "param"> & InputTypeBase<R, "query", "query"> & InputTypeForm<R> & InputTypeJson<R>>(route: R, handler: Handler<E, R["path"], I, OutputType<R>>, hook?: Hook<I, E, R["path"], OutputType<R>> | undefined) => this;
+    openapi: <R extends RouteConfig, I extends Input = InputTypeBase<R, "params", "param"> & InputTypeBase<R, "query", "query"> & InputTypeForm<R> & InputTypeJson<R>, P extends string = ConvertPathType<R["path"]>>(route: R, handler: Handler<E, P, I, OutputType<R>>, hook?: Hook<I, E, P, OutputType<R>> | undefined) => Hono<E, Schema<R["method"], P, I["in"], OutputType<R>>, BasePath>;
     getOpenAPIDocument: (config: OpenAPIObjectConfig) => openapi3_ts_oas30.OpenAPIObject;
     doc: (path: string, config: OpenAPIObjectConfig) => void;
 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as openapi3_ts_oas30 from 'openapi3-ts/oas30';
 import { RouteConfig, ZodRequestBody, ZodContentObject, ResponseConfig } from '@asteasolutions/zod-to-openapi';
 import { OpenAPIObjectConfig } from '@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator';
-import { Env, Hono, Input, Handler, Context, TypedResponse } from 'hono';
+import { Env, Hono, Input, Handler, Schema, Context, TypedResponse } from 'hono';
 import { AnyZodObject, z, ZodSchema, ZodError, ZodType } from 'zod';
 export { z } from 'zod';
 
@@ -14,18 +14,27 @@ type RequestTypes = {
 };
 type IsJson<T> = T extends string ? T extends `application/json${infer _Rest}` ? 'json' : never : never;
 type IsForm<T> = T extends string ? T extends `multipart/form-data${infer _Rest}` | `application/x-www-form-urlencoded${infer _Rest}` ? 'form' : never : never;
-type RequestPart<R extends RouteConfig, Part extends string> = Part extends keyof R['request'] ? R['request'][Part] : never;
+type RequestPart<R extends RouteConfig, Part extends string> = Part extends keyof R['request'] ? R['request'][Part] : {};
 type InputTypeBase<R extends RouteConfig, Part extends string, Type extends string> = R['request'] extends RequestTypes ? RequestPart<R, Part> extends AnyZodObject ? {
+    in: {
+        [K in Type]: z.input<RequestPart<R, Part>>;
+    };
     out: {
         [K in Type]: z.input<RequestPart<R, Part>>;
     };
 } : {} : {};
 type InputTypeJson<R extends RouteConfig> = R['request'] extends RequestTypes ? R['request']['body'] extends ZodRequestBody ? R['request']['body']['content'] extends ZodContentObject ? IsJson<keyof R['request']['body']['content']> extends never ? {} : R['request']['body']['content'][keyof R['request']['body']['content']]['schema'] extends ZodSchema<any> ? {
+    in: {
+        json: z.input<R['request']['body']['content'][keyof R['request']['body']['content']]['schema']>;
+    };
     out: {
         json: z.input<R['request']['body']['content'][keyof R['request']['body']['content']]['schema']>;
     };
 } : {} : {} : {} : {};
 type InputTypeForm<R extends RouteConfig> = R['request'] extends RequestTypes ? R['request']['body'] extends ZodRequestBody ? R['request']['body']['content'] extends ZodContentObject ? IsForm<keyof R['request']['body']['content']> extends never ? {} : R['request']['body']['content'][keyof R['request']['body']['content']]['schema'] extends ZodSchema<any> ? {
+    in: {
+        form: z.input<R['request']['body']['content'][keyof R['request']['body']['content']]['schema']>;
+    };
     out: {
         form: z.input<R['request']['body']['content'][keyof R['request']['body']['content']]['schema']>;
     };
@@ -38,10 +47,11 @@ type Hook<T, E extends Env, P extends string, O> = (result: {
     success: false;
     error: ZodError;
 }, c: Context<E, P>) => TypedResponse<O> | Promise<TypedResponse<T>> | void;
+type ConvertPathType<T extends string> = T extends `${infer _}/{${infer Param}}${infer _}` ? `/:${Param}` : T;
 declare class OpenAPIHono<E extends Env = Env, S = {}, BasePath extends string = '/'> extends Hono<E, S, BasePath> {
     #private;
     constructor();
-    openapi: <R extends RouteConfig, I extends Input = InputTypeBase<R, "params", "param"> & InputTypeBase<R, "query", "query"> & InputTypeForm<R> & InputTypeJson<R>>(route: R, handler: Handler<E, R["path"], I, OutputType<R>>, hook?: Hook<I, E, R["path"], OutputType<R>> | undefined) => this;
+    openapi: <R extends RouteConfig, I extends Input = InputTypeBase<R, "params", "param"> & InputTypeBase<R, "query", "query"> & InputTypeForm<R> & InputTypeJson<R>, P extends string = ConvertPathType<R["path"]>>(route: R, handler: Handler<E, P, I, OutputType<R>>, hook?: Hook<I, E, P, OutputType<R>> | undefined) => Hono<E, Schema<R["method"], P, I["in"], OutputType<R>>, BasePath>;
     getOpenAPIDocument: (config: OpenAPIObjectConfig) => openapi3_ts_oas30.OpenAPIObject;
     doc: (path: string, config: OpenAPIObjectConfig) => void;
 }

package/dist/index.js

@@ -58,7 +58,7 @@ var OpenAPIHono = class extends Hono {
           }
         }
       }
-      this.on([route.method], route.path, ...validators, handler);
+      this.on([route.method], route.path.replace(/\/{(.+)}/, "/:$1"), ...validators, handler);
       return this;
     };
     this.getOpenAPIDocument = (config) => {

package/package.json

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