@hono/zod-openapi 0.3.1 → 0.5.0

package/README.md

@@ -174,6 +174,15 @@ app.openapi(
 )
 ```
 
+### OpenAPI v3.1
+
+You can generate OpenAPI v3.1 spec using the following methods:
+
+```ts
+app.doc31('/docs', {openapi: '3.1.0'}) // new endpoint
+app.getOpenAPI31Document(, {openapi: '3.1.0'}) // raw json
+```
+
 ### The Registry
 
 You can access the [`OpenAPIRegistry`](https://github.com/asteasolutions/zod-to-openapi#the-registry) object via `app.openAPIRegistry`:
@@ -194,6 +203,18 @@ import { prettyJSON } from 'hono/pretty-json'
 app.use('/doc/*', prettyJSON())
 ```
 
+### Configure middleware for each endpoint
+
+You can configure middleware for each endpoint from a route created by `createRoute` as follows.
+
+```ts
+import { prettyJSON } from 'hono/pretty-json'
+import { cache } from 'honoc/cache'
+
+app.use(route.getRoutingPath(), prettyJSON(), cache({ cacheName: "my-cache" }))
+app.openapi(route, handler)
+```
+
 ### RPC Mode
 
 Zod OpenAPI Hono supports Hono's RPC mode. You can define types for the Hono Client as follows:
@@ -214,44 +235,9 @@ const client = hc<typeof appRoutes>('http://localhost:8787/')
 
 ## Limitations
 
-An instance of Zod OpenAPI Hono cannot be used as a "subApp" in conjunction with `rootApp.route('/api', subApp)`.
-Use `app.mount('/api', subApp.fetch)` instead.
+Be careful when combining `OpenAPIHono` instances with plain `Hono` instances. `OpenAPIHono` will merge the definitions of direct subapps, but plain `Hono` knows nothing about the OpenAPI spec additions. Similarly `OpenAPIHono` will not "dig" for instances deep inside a branch of plain `Hono` instances.
 
-```ts
-const api = OpenAPIHono()
-
-// ...
-
-// Set the `/api` as a base path in the document.
-api.get('/doc', (c) => {
-  const url = new URL(c.req.url)
-  url.pathname = '/api'
-  url.search = ''
-
-  return c.json(
-    // `api.getOpenAPIDocument()` will return a JSON object of the docs.
-    api.getOpenAPIDocument({
-      openapi: '3.0.0',
-      info: {
-        version: '1.0.0',
-        title: 'My API',
-      },
-      servers: [
-        {
-          url: `${url.toString()}`,
-        },
-      ],
-    })
-  )
-})
-
-const app = new Hono()
-
-// Mount the Open API app to `/api` in the main app.
-app.mount('/api', api.fetch)
-
-export default app
-```
+If you're migrating from plain `Hono` to `OpenAPIHono`, we recommend porting your top-level app, then working your way down the router tree.
 
 ## References
 

package/dist/index.cjs

@@ -30,10 +30,10 @@ var import_zod_to_openapi2 = require("@asteasolutions/zod-to-openapi");
 var import_zod_validator = require("@hono/zod-validator");
 var import_hono = require("hono");
 var import_zod = require("zod");
-var OpenAPIHono = class extends import_hono.Hono {
+var OpenAPIHono = class _OpenAPIHono extends import_hono.Hono {
   openAPIRegistry;
-  constructor() {
-    super();
+  constructor(init) {
+    super(init);
     this.openAPIRegistry = new import_zod_to_openapi.OpenAPIRegistry();
   }
   openapi = (route, handler, hook) => {
@@ -82,14 +82,73 @@ var OpenAPIHono = class extends import_hono.Hono {
     const document = generator.generateDocument(config);
     return document;
   };
+  getOpenAPI31Document = (config) => {
+    const generator = new import_zod_to_openapi.OpenApiGeneratorV31(this.openAPIRegistry.definitions);
+    const document = generator.generateDocument(config);
+    return document;
+  };
   doc = (path, config) => {
     this.get(path, (c) => {
       const document = this.getOpenAPIDocument(config);
       return c.json(document);
     });
   };
+  doc31 = (path, config) => {
+    this.get(path, (c) => {
+      const document = this.getOpenAPI31Document(config);
+      return c.json(document);
+    });
+  };
+  route(path, app) {
+    super.route(path, app);
+    if (!(app instanceof _OpenAPIHono)) {
+      return this;
+    }
+    app.openAPIRegistry.definitions.forEach((def) => {
+      switch (def.type) {
+        case "component":
+          return this.openAPIRegistry.registerComponent(
+            def.componentType,
+            def.name,
+            def.component
+          );
+        case "route":
+          return this.openAPIRegistry.registerPath({
+            ...def.route,
+            path: `${path}${def.route.path}`
+          });
+        case "webhook":
+          return this.openAPIRegistry.registerWebhook({
+            ...def.webhook,
+            path: `${path}${def.webhook.path}`
+          });
+        case "schema":
+          return this.openAPIRegistry.register(
+            def.schema._def.openapi._internal.refId,
+            def.schema
+          );
+        case "parameter":
+          return this.openAPIRegistry.registerParameter(
+            def.schema._def.openapi._internal.refId,
+            def.schema
+          );
+        default: {
+          const errorIfNotExhaustive = def;
+          throw new Error(`Unknown registry type: ${errorIfNotExhaustive}`);
+        }
+      }
+    });
+    return this;
+  }
+};
+var createRoute = (routeConfig) => {
+  return {
+    ...routeConfig,
+    getRoutingPath() {
+      return routeConfig.path.replaceAll(/\/{(.+?)}/g, "/:$1");
+    }
+  };
 };
-var createRoute = (routeConfig) => routeConfig;
 (0, import_zod_to_openapi2.extendZodWithOpenApi)(import_zod.z);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -1,7 +1,10 @@
+import * as openapi3_ts_oas31 from 'openapi3-ts/oas31';
 import * as openapi3_ts_oas30 from 'openapi3-ts/oas30';
 import { OpenAPIRegistry, RouteConfig, ZodRequestBody, ZodContentObject, ResponseConfig } from '@asteasolutions/zod-to-openapi';
 import { OpenAPIObjectConfig } from '@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator';
 import { Env, Schema, Hono, Input, Handler, ToSchema, Context, TypedResponse } from 'hono';
+import { MergeSchemaPath, MergePath } from 'hono/dist/types/types';
+import { RemoveBlankRecord } from 'hono/utils/types';
 import { AnyZodObject, z, ZodSchema, ZodError, ZodType } from 'zod';
 export { z } from 'zod';
 
@@ -49,15 +52,23 @@ type Hook<T, E extends Env, P extends string, O> = (result: {
 }, c: Context<E, P>) => TypedResponse<O> | Promise<TypedResponse<T>> | void;
 type ConvertPathType<T extends string> = T extends `${infer _}/{${infer Param}}${infer _}` ? `/:${Param}` : T;
 type HandlerResponse<O> = TypedResponse<O> | Promise<TypedResponse<O>>;
+type HonoInit = ConstructorParameters<typeof Hono>[0];
 declare class OpenAPIHono<E extends Env = Env, S extends Schema = {}, BasePath extends string = '/'> extends Hono<E, S, BasePath> {
     openAPIRegistry: OpenAPIRegistry;
-    constructor();
-    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"]>>(route: R, handler: Handler<E, P, I, HandlerResponse<OutputType<R>>>, hook?: Hook<I, E, P, OutputType<R>> | undefined) => Hono<E, ToSchema<R["method"], P, I["in"], OutputType<R>>, BasePath>;
+    constructor(init?: HonoInit);
+    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"]>>(route: R, handler: Handler<E, P, I, HandlerResponse<OutputType<R>>>, hook?: Hook<I, E, P, OutputType<R>> | undefined) => OpenAPIHono<E, ToSchema<R["method"], P, I["in"], OutputType<R>>, BasePath>;
     getOpenAPIDocument: (config: OpenAPIObjectConfig) => openapi3_ts_oas30.OpenAPIObject;
+    getOpenAPI31Document: (config: OpenAPIObjectConfig) => openapi3_ts_oas31.OpenAPIObject;
     doc: (path: string, config: OpenAPIObjectConfig) => void;
+    doc31: (path: string, config: OpenAPIObjectConfig) => void;
+    route<SubPath extends string, SubEnv extends Env, SubSchema extends Schema, SubBasePath extends string>(path: SubPath, app: Hono<SubEnv, SubSchema, SubBasePath>): OpenAPIHono<E, MergeSchemaPath<SubSchema, MergePath<BasePath, SubPath>> & S, BasePath>;
+    route<SubPath extends string>(path: SubPath): Hono<E, RemoveBlankRecord<S>, BasePath>;
 }
+type RoutingPath<P extends string> = P extends `${infer Head}/{${infer Param}}${infer Tail}` ? `${Head}/:${Param}${RoutingPath<Tail>}` : P;
 declare const createRoute: <P extends string, R extends Omit<RouteConfig, "path"> & {
     path: P;
-}>(routeConfig: R) => R;
+}>(routeConfig: R) => R & {
+    getRoutingPath(): RoutingPath<R["path"]>;
+};
 
 export { OpenAPIHono, createRoute };

package/dist/index.d.ts

@@ -1,7 +1,10 @@
+import * as openapi3_ts_oas31 from 'openapi3-ts/oas31';
 import * as openapi3_ts_oas30 from 'openapi3-ts/oas30';
 import { OpenAPIRegistry, RouteConfig, ZodRequestBody, ZodContentObject, ResponseConfig } from '@asteasolutions/zod-to-openapi';
 import { OpenAPIObjectConfig } from '@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator';
 import { Env, Schema, Hono, Input, Handler, ToSchema, Context, TypedResponse } from 'hono';
+import { MergeSchemaPath, MergePath } from 'hono/dist/types/types';
+import { RemoveBlankRecord } from 'hono/utils/types';
 import { AnyZodObject, z, ZodSchema, ZodError, ZodType } from 'zod';
 export { z } from 'zod';
 
@@ -49,15 +52,23 @@ type Hook<T, E extends Env, P extends string, O> = (result: {
 }, c: Context<E, P>) => TypedResponse<O> | Promise<TypedResponse<T>> | void;
 type ConvertPathType<T extends string> = T extends `${infer _}/{${infer Param}}${infer _}` ? `/:${Param}` : T;
 type HandlerResponse<O> = TypedResponse<O> | Promise<TypedResponse<O>>;
+type HonoInit = ConstructorParameters<typeof Hono>[0];
 declare class OpenAPIHono<E extends Env = Env, S extends Schema = {}, BasePath extends string = '/'> extends Hono<E, S, BasePath> {
     openAPIRegistry: OpenAPIRegistry;
-    constructor();
-    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"]>>(route: R, handler: Handler<E, P, I, HandlerResponse<OutputType<R>>>, hook?: Hook<I, E, P, OutputType<R>> | undefined) => Hono<E, ToSchema<R["method"], P, I["in"], OutputType<R>>, BasePath>;
+    constructor(init?: HonoInit);
+    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"]>>(route: R, handler: Handler<E, P, I, HandlerResponse<OutputType<R>>>, hook?: Hook<I, E, P, OutputType<R>> | undefined) => OpenAPIHono<E, ToSchema<R["method"], P, I["in"], OutputType<R>>, BasePath>;
     getOpenAPIDocument: (config: OpenAPIObjectConfig) => openapi3_ts_oas30.OpenAPIObject;
+    getOpenAPI31Document: (config: OpenAPIObjectConfig) => openapi3_ts_oas31.OpenAPIObject;
     doc: (path: string, config: OpenAPIObjectConfig) => void;
+    doc31: (path: string, config: OpenAPIObjectConfig) => void;
+    route<SubPath extends string, SubEnv extends Env, SubSchema extends Schema, SubBasePath extends string>(path: SubPath, app: Hono<SubEnv, SubSchema, SubBasePath>): OpenAPIHono<E, MergeSchemaPath<SubSchema, MergePath<BasePath, SubPath>> & S, BasePath>;
+    route<SubPath extends string>(path: SubPath): Hono<E, RemoveBlankRecord<S>, BasePath>;
 }
+type RoutingPath<P extends string> = P extends `${infer Head}/{${infer Param}}${infer Tail}` ? `${Head}/:${Param}${RoutingPath<Tail>}` : P;
 declare const createRoute: <P extends string, R extends Omit<RouteConfig, "path"> & {
     path: P;
-}>(routeConfig: R) => R;
+}>(routeConfig: R) => R & {
+    getRoutingPath(): RoutingPath<R["path"]>;
+};
 
 export { OpenAPIHono, createRoute };

package/dist/index.js

@@ -1,13 +1,13 @@
 // src/index.ts
-import { OpenApiGeneratorV3, OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
+import { OpenApiGeneratorV3, OpenApiGeneratorV31, OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
 import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
 import { zValidator } from "@hono/zod-validator";
 import { Hono } from "hono";
 import { z, ZodType } from "zod";
-var OpenAPIHono = class extends Hono {
+var OpenAPIHono = class _OpenAPIHono extends Hono {
   openAPIRegistry;
-  constructor() {
-    super();
+  constructor(init) {
+    super(init);
     this.openAPIRegistry = new OpenAPIRegistry();
   }
   openapi = (route, handler, hook) => {
@@ -56,14 +56,73 @@ var OpenAPIHono = class extends Hono {
     const document = generator.generateDocument(config);
     return document;
   };
+  getOpenAPI31Document = (config) => {
+    const generator = new OpenApiGeneratorV31(this.openAPIRegistry.definitions);
+    const document = generator.generateDocument(config);
+    return document;
+  };
   doc = (path, config) => {
     this.get(path, (c) => {
       const document = this.getOpenAPIDocument(config);
       return c.json(document);
     });
   };
+  doc31 = (path, config) => {
+    this.get(path, (c) => {
+      const document = this.getOpenAPI31Document(config);
+      return c.json(document);
+    });
+  };
+  route(path, app) {
+    super.route(path, app);
+    if (!(app instanceof _OpenAPIHono)) {
+      return this;
+    }
+    app.openAPIRegistry.definitions.forEach((def) => {
+      switch (def.type) {
+        case "component":
+          return this.openAPIRegistry.registerComponent(
+            def.componentType,
+            def.name,
+            def.component
+          );
+        case "route":
+          return this.openAPIRegistry.registerPath({
+            ...def.route,
+            path: `${path}${def.route.path}`
+          });
+        case "webhook":
+          return this.openAPIRegistry.registerWebhook({
+            ...def.webhook,
+            path: `${path}${def.webhook.path}`
+          });
+        case "schema":
+          return this.openAPIRegistry.register(
+            def.schema._def.openapi._internal.refId,
+            def.schema
+          );
+        case "parameter":
+          return this.openAPIRegistry.registerParameter(
+            def.schema._def.openapi._internal.refId,
+            def.schema
+          );
+        default: {
+          const errorIfNotExhaustive = def;
+          throw new Error(`Unknown registry type: ${errorIfNotExhaustive}`);
+        }
+      }
+    });
+    return this;
+  }
+};
+var createRoute = (routeConfig) => {
+  return {
+    ...routeConfig,
+    getRoutingPath() {
+      return routeConfig.path.replaceAll(/\/{(.+?)}/g, "/:$1");
+    }
+  };
 };
-var createRoute = (routeConfig) => routeConfig;
 extendZodWithOpenApi(z);
 export {
   OpenAPIHono,

package/package.json

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