Establish a well-known URI for discovery

[earth2marsh]

People should be able to discover by convention whether a description document exists, such as /openapi.yaml or just use /openapi and provide YAML by default and allow content-negotiation if you prefer another format.

Might also be wise to finally register media types, like application/openapi+json and application/openapi+yaml?

[darrelmiller]

Media type registration for OpenAPI and JSON Schema is under way https://ietf-wg-httpapi.github.io/mediatypes/draft-ietf-httpapi-rest-api-mediatypes.html
Media type registration for YAML is currently in working group last call.
https://ietf-wg-httpapi.github.io/mediatypes/draft-ietf-httpapi-yaml-mediatypes.html

If we create a well-known identifier identifier it is worth considering using the IETF syntax for well known resources https://www.rfc-editor.org/rfc/rfc8615

[st3v3-t]

This has a lot of merit and I like the re-use of RFC8615 by exposing (for example) /.well-known/openapi .

From a practical stance our org has many openapi spec documents and wouldn't be able to return a single coherent one. I imagine we would therefore return Info (+externalDocs?) as a pointer to our developer portal. That still feels in the spirit of OpenAPI discovery - especially for orgs where documentation lives on a different host.

[bpedro]

That's a great point, @st3v3-t! Have you seen http://apisjson.org/? Its goal is to help API providers describe all their APIs.

Perhaps there could be a way to integrate the well-known URI with APIs.json?