@hono/zod-openapi 0.8.6 → 0.9.0

package/README.md

@@ -231,7 +231,7 @@ 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
+app.getOpenAPI31Document({openapi: '3.1.0'}) // raw json
 ```
 
 ### The Registry
@@ -284,12 +284,91 @@ const appRoutes = app.openapi(route, (c) => {
 const client = hc<typeof appRoutes>('http://localhost:8787/')
 ```
 
+## Tips
+
+### How to register components
+
+You can register components to the registry as follows:
+
+```ts
+app.openAPIRegistry.registerComponent('schemas', {
+  User: UserSchema,
+})
+```
+
+About this feature, please refer to [the "Zod to OpenAPI" resource / Defining Custom Components](https://github.com/asteasolutions/zod-to-openapi#defining-custom-components)
+
+### How to setup authorization
+
+You can setup authorization as follows:
+
+eg. Bearer Auth
+
+Register the security scheme:
+
+```ts
+app.openAPIRegistry.registerComponent('securitySchema', {
+  Bearer: {
+    type: 'http',
+    scheme: 'bearer',
+  },
+})
+```
+
+And setup the security scheme for specific routes:
+
+```ts
+const route = createRoute({
+  // ...
+  security: [
+    {
+      Bearer: [],
+    },
+  ],
+})
+```
+
+### How to access context in app.doc
+
+You can access the context in `app.doc` as follows:
+
+```ts
+app.doc('/doc', c => ({
+  openapi: '3.0.0',
+  info: {
+    version: '1.0.0',
+    title: 'My API',
+  },
+  servers: [
+    {
+      url: new URL(c.req.url).hostname,
+      description: 'Current environment',
+    },
+  ],
+}))
+```
+
 ## Limitations
 
+### Combining with `Hono`
+
 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.
 
 If you're migrating from plain `Hono` to `OpenAPIHono`, we recommend porting your top-level app, then working your way down the router tree.
 
+### Header keys
+
+Header keys that you define in your schema must be in lowercase.
+
+```ts
+const HeadersSchema = z.object({
+  // Header keys must be in lowercase, `Authorization` is not allowed.
+  authorization: z.string().openapi({
+    example: 'Bearer SECRET',
+  }),
+})
+```
+
 ## References
 
 - [Hono](https://hono.dev/)

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import * as openapi3_ts_oas31 from 'openapi3-ts/oas31';
 import * as openapi3_ts_oas30 from 'openapi3-ts/oas30';
 import { RouteConfig, OpenAPIRegistry, ZodRequestBody, ZodContentObject, ResponseConfig } from '@asteasolutions/zod-to-openapi';
 import { OpenAPIObjectConfig } from '@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator';
-import { Env, Input, Handler, Schema, Hono, ToSchema, Context, TypedResponse } from 'hono';
+import { Env, Input, Handler, Context, Schema, Hono, ToSchema, TypedResponse } from 'hono';
 import { MergeSchemaPath, MergePath } from 'hono/types';
 import { RemoveBlankRecord } from 'hono/utils/types';
 import { AnyZodObject, z, ZodSchema, ZodError, ZodType } from 'zod';
@@ -62,6 +62,7 @@ type OpenAPIHonoOptions<E extends Env> = {
 type HonoInit<E extends Env> = ConstructorParameters<typeof Hono>[0] & OpenAPIHonoOptions<E>;
 type RouteHandler<R extends RouteConfig, E extends Env = Env, I extends Input = InputTypeParam<R> & InputTypeQuery<R> & InputTypeHeader<R> & InputTypeCookie<R> & InputTypeForm<R> & InputTypeJson<R>, P extends string = ConvertPathType<R['path']>> = Handler<E, P, I, HandlerResponse<OutputType<R>>>;
 type RouteHook<R extends RouteConfig, E extends Env = Env, I extends Input = InputTypeParam<R> & InputTypeQuery<R> & InputTypeHeader<R> & InputTypeCookie<R> & InputTypeForm<R> & InputTypeJson<R>, P extends string = ConvertPathType<R['path']>> = Hook<I, E, P, OutputType<R>>;
+type OpenAPIObjectConfigure<E extends Env, P extends string> = OpenAPIObjectConfig | ((context: Context<E, P>) => OpenAPIObjectConfig);
 declare class OpenAPIHono<E extends Env = Env, S extends Schema = {}, BasePath extends string = '/'> extends Hono<E, S, BasePath> {
     openAPIRegistry: OpenAPIRegistry;
     defaultHook?: OpenAPIHonoOptions<E>['defaultHook'];
@@ -69,8 +70,8 @@ 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"]>>(route: R, handler: Handler<E, P, I, HandlerResponse<OutputType<R>>>, hook?: Hook<I, E, P, OutputType<R>> | undefined) => OpenAPIHono<E, S & ToSchema<R["method"], P, I["in"], OutputType<R>>, BasePath>;
     getOpenAPIDocument: (config: OpenAPIObjectConfig) => openapi3_ts_oas30.OpenAPIObject;
     getOpenAPI31Document: (config: OpenAPIObjectConfig) => openapi3_ts_oas31.OpenAPIObject;
-    doc: <P extends string>(path: P, config: OpenAPIObjectConfig) => OpenAPIHono<E, S & ToSchema<"get", P, {}, {}>, BasePath>;
-    doc31: <P extends string>(path: P, config: OpenAPIObjectConfig) => OpenAPIHono<E, S & ToSchema<"get", P, {}, {}>, BasePath>;
+    doc: <P extends string>(path: P, configure: OpenAPIObjectConfigure<E, P>) => OpenAPIHono<E, S & ToSchema<"get", P, {}, {}>, BasePath>;
+    doc31: <P extends string>(path: P, configure: OpenAPIObjectConfigure<E, P>) => OpenAPIHono<E, S & ToSchema<"get", P, {}, {}>, BasePath>;
     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>;
     basePath<SubPath extends string>(path: SubPath): OpenAPIHono<E, S, MergePath<BasePath, SubPath>>;
@@ -82,4 +83,4 @@ declare const createRoute: <P extends string, R extends Omit<RouteConfig, "path"
     getRoutingPath(): RoutingPath<R["path"]>;
 };
 
-export { OpenAPIHono, OpenAPIHonoOptions, RouteHandler, RouteHook, createRoute };
+export { OpenAPIHono, OpenAPIHonoOptions, OpenAPIObjectConfigure, RouteHandler, RouteHook, createRoute };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as openapi3_ts_oas31 from 'openapi3-ts/oas31';
 import * as openapi3_ts_oas30 from 'openapi3-ts/oas30';
 import { RouteConfig, OpenAPIRegistry, ZodRequestBody, ZodContentObject, ResponseConfig } from '@asteasolutions/zod-to-openapi';
 import { OpenAPIObjectConfig } from '@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator';
-import { Env, Input, Handler, Schema, Hono, ToSchema, Context, TypedResponse } from 'hono';
+import { Env, Input, Handler, Context, Schema, Hono, ToSchema, TypedResponse } from 'hono';
 import { MergeSchemaPath, MergePath } from 'hono/types';
 import { RemoveBlankRecord } from 'hono/utils/types';
 import { AnyZodObject, z, ZodSchema, ZodError, ZodType } from 'zod';
@@ -62,6 +62,7 @@ type OpenAPIHonoOptions<E extends Env> = {
 type HonoInit<E extends Env> = ConstructorParameters<typeof Hono>[0] & OpenAPIHonoOptions<E>;
 type RouteHandler<R extends RouteConfig, E extends Env = Env, I extends Input = InputTypeParam<R> & InputTypeQuery<R> & InputTypeHeader<R> & InputTypeCookie<R> & InputTypeForm<R> & InputTypeJson<R>, P extends string = ConvertPathType<R['path']>> = Handler<E, P, I, HandlerResponse<OutputType<R>>>;
 type RouteHook<R extends RouteConfig, E extends Env = Env, I extends Input = InputTypeParam<R> & InputTypeQuery<R> & InputTypeHeader<R> & InputTypeCookie<R> & InputTypeForm<R> & InputTypeJson<R>, P extends string = ConvertPathType<R['path']>> = Hook<I, E, P, OutputType<R>>;
+type OpenAPIObjectConfigure<E extends Env, P extends string> = OpenAPIObjectConfig | ((context: Context<E, P>) => OpenAPIObjectConfig);
 declare class OpenAPIHono<E extends Env = Env, S extends Schema = {}, BasePath extends string = '/'> extends Hono<E, S, BasePath> {
     openAPIRegistry: OpenAPIRegistry;
     defaultHook?: OpenAPIHonoOptions<E>['defaultHook'];
@@ -69,8 +70,8 @@ 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"]>>(route: R, handler: Handler<E, P, I, HandlerResponse<OutputType<R>>>, hook?: Hook<I, E, P, OutputType<R>> | undefined) => OpenAPIHono<E, S & ToSchema<R["method"], P, I["in"], OutputType<R>>, BasePath>;
     getOpenAPIDocument: (config: OpenAPIObjectConfig) => openapi3_ts_oas30.OpenAPIObject;
     getOpenAPI31Document: (config: OpenAPIObjectConfig) => openapi3_ts_oas31.OpenAPIObject;
-    doc: <P extends string>(path: P, config: OpenAPIObjectConfig) => OpenAPIHono<E, S & ToSchema<"get", P, {}, {}>, BasePath>;
-    doc31: <P extends string>(path: P, config: OpenAPIObjectConfig) => OpenAPIHono<E, S & ToSchema<"get", P, {}, {}>, BasePath>;
+    doc: <P extends string>(path: P, configure: OpenAPIObjectConfigure<E, P>) => OpenAPIHono<E, S & ToSchema<"get", P, {}, {}>, BasePath>;
+    doc31: <P extends string>(path: P, configure: OpenAPIObjectConfigure<E, P>) => OpenAPIHono<E, S & ToSchema<"get", P, {}, {}>, BasePath>;
     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>;
     basePath<SubPath extends string>(path: SubPath): OpenAPIHono<E, S, MergePath<BasePath, SubPath>>;
@@ -82,4 +83,4 @@ declare const createRoute: <P extends string, R extends Omit<RouteConfig, "path"
     getRoutingPath(): RoutingPath<R["path"]>;
 };
 
-export { OpenAPIHono, OpenAPIHonoOptions, RouteHandler, RouteHook, createRoute };
+export { OpenAPIHono, OpenAPIHonoOptions, OpenAPIObjectConfigure, RouteHandler, RouteHook, createRoute };

package/dist/index.js

@@ -90,14 +90,16 @@ var OpenAPIHono = class _OpenAPIHono extends import_hono.Hono {
     const document = generator.generateDocument(config);
     return document;
   };
-  doc = (path, config) => {
+  doc = (path, configure) => {
     return this.get(path, (c) => {
+      const config = typeof configure === "function" ? configure(c) : configure;
       const document = this.getOpenAPIDocument(config);
       return c.json(document);
     });
   };
-  doc31 = (path, config) => {
+  doc31 = (path, configure) => {
     return this.get(path, (c) => {
+      const config = typeof configure === "function" ? configure(c) : configure;
       const document = this.getOpenAPI31Document(config);
       return c.json(document);
     });

package/dist/index.mjs

@@ -68,14 +68,16 @@ var OpenAPIHono = class _OpenAPIHono extends Hono {
     const document = generator.generateDocument(config);
     return document;
   };
-  doc = (path, config) => {
+  doc = (path, configure) => {
     return this.get(path, (c) => {
+      const config = typeof configure === "function" ? configure(c) : configure;
       const document = this.getOpenAPIDocument(config);
       return c.json(document);
     });
   };
-  doc31 = (path, config) => {
+  doc31 = (path, configure) => {
     return this.get(path, (c) => {
+      const config = typeof configure === "function" ? configure(c) : configure;
       const document = this.getOpenAPI31Document(config);
       return c.json(document);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hono/zod-openapi",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "description": "A wrapper class of Hono which supports OpenAPI.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -42,6 +42,7 @@
     "zod": "3.*"
   },
   "devDependencies": {
+    "@hono/zod-validator": "^0.1.11",
     "hono": "^3.9.1",
     "zod": "^3.22.1"
   },