This is an interesting feature, but I think it deserves to be an epic, there's a lot of work to be done here.

First, to clarify, which API are you talking about it? Core REST API or API Gateway. The former is a subtask of the latter and thus smaller/easier.

For OpenAPI support in Core REST API, I think @apaskulin has some very good notes and tickets that she could add here.

As for gateway OpenAPI, things get more interesting. API Gateway collects various APIs implemented in various backends into the same structure, ideally hiding the implementation of the specific endpoint. It will also probably mangle some of the parameters/paths to make the user-facing API more consistent. Thus, the spec of the API provided by the gateway has to be collected from various backends, merged and mangled the same way gateway is mangling the paths. In RESTBase we have chosen the easy path and just copy-pasted the specs from individual services when exposing them, but with experience we've come to an understanding that it was probably a mistake - copying the specs is too much overhead and is doomed to diverge.

Thus, to support OpenAPI in the gateway, we would probably need to create a spec service. A service would be configured with exposed endpoints and pointers to where to download the specs from individual services and have the ability to merge/mangle them. Additionally, we could annotate the paths with various tags and have it support json-path-like routing for fetching segments of the spec. That would allow us to generate executable snippets/docs for parts of the API, potentially embed them on the API Portal wiki. This has the potential to be very very cool.

If we ever deploy RDS for api-gateway envoy, the spec service could fetch it's config from RDS as well.