Customizing OpenAPI schema generation

[ssoroka-tc]

I want to implement something like Stripe's versioning where it's date based, and I can define two routes for the same url with different dates. To support this, I'm writing a custom router that will figure out which date matches based on an X-Version header supplied.
What I'd really love is to generate different OpenAPI schemas for each date defined (and ideally allow the user to select the date from the /docs endpoint)

What future do you see for being able to customize schema generation? Could these things be made configurable in the future? what effort would that involve? Any tips for possibly being able to support that today?

[danielgtaylor]

@ssoroka-tc I don't think that's possible today as a single operation can only have one input/output defined and the operation is keyed on the path. You could certainly build something like this, i.e. re-implement huma.Register where instead of a single handler it takes multiple handlers mapped by some input like a header value. It would need to generate all the different schemas and keep track of it all as if it was multiple operations, but all for the same path. Then you'd have to customize the docs page to show things by version somehow (pre-processing the OpenAPI maybe?). It's doable but probably significant effort.

BTW an alternative implementation is to actually have multiple versions of the service deployed, and have a proxy forward based on the version header:

graph LR
  User --->|X-Version: 3| Proxy
  Proxy ---> ServiceV1
  Proxy ---> ServiceV2
  Proxy --->|goes here| ServiceV3

Loading

Each running version would have its own OpenAPI, and you could make a wrapper docs page to select between versions.