Support discovering OpenAPI document from `Link` header?

I’m looking at various options to “upgrade” a simple API (HTTP POST of CloudEvents) to allow clients and servers to be able to extend into more complex OpenAPI space (e.g. “what events are you interested in” or “what types of events might be returned in the HTTP response”).

One attractive option would be to provide a Link header pointing to the OpenAPI spec on the existing endpoint to provide a hint that upgrade is available.

I don’t see a documented rel (relation) value for OpenAPI; would something like “oas-3.0” be a reasonable value?

[MikeRalphson]

I think more generically service-desc might suit the bill. See https://tools.ietf.org/html/rfc8631

See #1511 #724 #734 for previous discussions including describedBy, and #110 for a proposed media-type for OAS documents.

[MikeRalphson]

I recall @darrelmiller had some objection to using a .well-known URI for this case - could we document it here? It may have been that an OpenAPI document doesn’t meet the criteria of

the discovery of information about an origin … (sometimes called “site-wide metadata”)

Of course one issue it doesn’t cater for is an organisation having many APIs (which could be handled by something like apis.json). There is also the schema.org WebAPI type in this discovery space.