[@hono/zod-openapi] securitySchemes not being applied from config

[Soviut]

Which middleware has the bug?

@hono/zod-openapi

What version of the middleware?

1.1.0

What version of Hono are you using?

4.8.0

What runtime/platform is your app running on? (with version if possible)

Node

What steps can reproduce the bug?

create an openapi config like this

import { serve } from '@hono/node-server'

const OPENAPI_CONFIG = {
  openapi: '3.1.0',
  externalDocs: {
    description: 'My API',
    url: 'example.com',
  },
  info: {
    version: '0.0.1',
    title: 'My API',
  },
  components: {
    securitySchemes: {
      bearerAuth: {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
        description: 'JWT Authentication',
      },
    },
  },
}

const app = new OpenAPIHono()

app.doc31('/doc', OPENAPI_CONFIG)

serve(app, (info) => {
  console.log(`Listening on http://localhost:${info.port}`)
})

Then visit http://localhost:3000/doc

Observe that the components section of the doc is missing the securitySchemes section entirely.

{
  "openapi": "3.1.0",
  "externalDocs": {
    "description": "My Api",
    "url": "example.com"
  },
  "info": {
    "version": "0.0.1",
    "title": "My API"
  },
  "components": {
    "schemas": {},
    "parameters": {}
  },
  "paths": {
    /* ... */
  },
  "webhooks": {}
}

Additionally, anything put under the components section seems to be ignored or overwritten in the doc.

What is the expected behavior?

The securitySchemes defined in the config should be kept.

What do you see instead?

  "components": {
    "schemas": {},
    "parameters": {}
  }

Anything in the config that is put under components gets removed.

Additional information

No response

[luksch42]

As a workaround you could register the securitySchemas right before calling app.doc31

app.openAPIRegistry.registerComponent("securitySchemes", "bearerAuth", {
      type: 'http',
      scheme: 'bearer',
      bearerFormat: 'JWT',
      description: 'JWT Authentication',
});

[Soviut]

@luksch42 thanks, I figured something like this was possible. This definitely should be added to the documentation. Once I've had a little time to play with this I'll probably make a docs PR.

[yusukebe]

@luksch42 Thanks!

@Soviut

This definitely should be added to the documentation. Once I've had a little time to play with this I'll probably make a docs PR.

We will be happy if you create a PR!

[Soviut]

@luksch42 This worked great. I can see the securitySchemes in the document. Also, their usage in the routes is working in my frontend generator; it recognizes the routes require an authorization header and is sending it now.

[Soviut]

@yusukebe When I create docs for this I was thinking I'd break it into two seconds. The first section would just explain how to use app.openAPIRegistry to register components. The second section would be specifically about how to set up securitySchemes and use them in a route.

For now, I'll probably just show an example of the bearerAuth scheme since that's very common and documented outside of Hono.

What do you think?

[yusukebe]

@Soviut

Sounds good! Please go ahead with it.