OpenAPI configuration object

[patogordo]

I really liked the defineRouteMeta() approach for documenting the API, but I'm curious about how it will handle the components and other global objects in the future.

Currently, it probably will looks something like this:

export default defineNitroConfig({
  experimental: {
    openAPI: true,
  },
  openAPI: {
    meta: {
      title: 'My Awesome Project',
      description: 'This might become the next big thing.',
      version: '1.0'
    },
    components: {
      schemas: {
        Error: {
          type: 'object',
          required: ['status_code', 'message'],
          properties: {
            status_code: {
              type: 'integer',
              format: 'int32'
            },
            message: {
              type: 'string'
            }
          }
        }
      }
    }
  }
})

I'm not sure if placing it all in nitro.config.ts is the best idea because it will increase the file size when new Schemas, Parameters, RequestBodies...etc, entities number grow.

One possibility could be something like this, similar to the custom error handler:

// nitro.config.ts
export default defineNitroConfig({
  experimental: {
    openAPI: true,
  },
  openAPIAdapter: "~/openapi"
})

Adapter was the best name i thought, because it isn't a handler and also not a plugin.

// openapi.ts
export default defineOpenAPIAdapter({
  meta: {
    title: 'My Awesome Project',
    description: 'This might become the next big thing.',
    version: '1.0'
  },
  components: {
    schemas: {
      Error: {
        type: 'object',
        required: ['status_code', 'message'],
        properties: {
          status_code: {
            type: 'integer',
            format: 'int32'
          },
          message: {
            type: 'string'
          }
        }
      }
    }
  }
})

This way, the configuration is isolated and treat all OpenAPI concerns. What you guys think?

[chadxz]

Ideally schemas can be built and re-used across multiple routes. I'd be fine with defining things like security schemes and other one-time setup components in the config. If we can use evaluated code in defineRouteMeta (#2974) then we can perhaps have components defined as Zod schemas (with zod-openapi) and registered using something like what you are describing, then use the references in our route meta.