Add ability to exclude routes from OpenAPI docs

.changeset/hot-moles-fix.md

@@ -0,0 +1,5 @@
+---
+'@hono/zod-openapi': patch
+---
+
+Add ability to exclude specific routes from OpenAPI docs

packages/zod-openapi/README.md

@@ -451,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`

packages/zod-openapi/src/index.ts

@@ -43,6 +43,7 @@ type MaybePromise<T> = Promise<T> | T
 
 export type RouteConfig = RouteConfigBase & {
   middleware?: MiddlewareHandler | MiddlewareHandler[]
+  hide?: boolean
 }
 
 type RequestTypes = {
@@ -418,7 +419,7 @@ export class OpenAPIHono<
       InputTypeJson<R>,
     P extends string = ConvertPathType<R['path']>
   >(
-    { middleware: routeMiddleware, ...route }: R,
+    { middleware: routeMiddleware, hide, ...route }: R,
     handler: Handler<
       // use the env from the middleware if it's defined
       R['middleware'] extends MiddlewareHandler[] | MiddlewareHandler
@@ -462,7 +463,9 @@ export class OpenAPIHono<
     S & ToSchema<R['method'], MergePath<BasePath, P>, I, RouteConfigToTypedResponse<R>>,
     BasePath
   > => {
-    this.openAPIRegistry.registerPath(route)
+    if (!hide) {
+      this.openAPIRegistry.registerPath(route)
+    }
 
     const validators: MiddlewareHandler[] = []
 

packages/zod-openapi/test/index.test.ts

@@ -1923,3 +1923,48 @@ describe('Generate YAML', () => {
     expect(() => stringify(doc)).to.not.throw()
   })
 })
+
+describe('Hide Routes', () => {
+  it('Should hide the route', async () => {
+    const app = new OpenAPIHono()
+    app.openapi(
+      createRoute({
+        method: 'get',
+        hide: true,
+        path: '/books',
+        responses: {
+          200: {
+            description: 'Books',
+            content: {
+              'application/json': {
+                schema: z.array(
+                  z.object({
+                    title: z.string(),
+                  })
+                ),
+              },
+            },
+          },
+        },
+      }),
+      (c) => c.json([{ title: 'foo' }])
+    )
+    const doc = app.getOpenAPIDocument({
+      openapi: '3.0.0',
+      info: {
+        title: 'My API',
+        version: '1.0.0',
+      },
+    })
+
+    const doc31 = app.getOpenAPI31Document({
+      openapi: '3.1.0',
+      info: {
+        title: 'My API',
+        version: '1.0.0',
+      },
+    })
+    expect(doc.paths).not.toHaveProperty('/books')
+    expect(doc31.paths).not.toHaveProperty('/books')
+  })
+})