OpenAPI or swagger.json auto discovery

问题:

Is there any spec or convention on URL where one should place swagger.json (or whatever name it is agreed) so that public API of my site can be automatically discovered?

回答1:

Updated 19 April 2017: The OpenAPI Wiki answer I gave previously is "for a very very very old version of the spec". The same source states that for 2.0 the standard is swagger.json, for 3.0 it changes to openapi.json.

Original answer:

The OpenAPI Wiki recommends using an /api-docs endpoint, at least for server APIs. I've seen several sites in the wild that use that, and it's our shop standard.

Hope that helps.

回答2:

How about serving the Swagger JSON in an HTTP response body, in response to an OPTIONS request for the URL / ?

This is specifically permitted by the relevant RFC.

Further, consider implementing HATEOAS, as strongly advocated by Roy Fielding.

回答3:

Okay. OpenAPI 3.0 still lacking auto-discovery mechanism, I try to propose a scheme based on some things that were already working:

1. https://example.com/.well-known/schema-discovery is a JSON document pointing to array of available schemas:

   [
     {
       "schema_url": "/openapi.json",
       "schema_type": "openapi-3.0"
     },
     {
       "schema_url": "/v2/openapi.json",
       "schema_type": "openapi-3.0"
     }
   ]
   

2. If there is only one version of API, then https://example.com/openapi.json should be enough.

3. HTTP Headers. I remember somebody from Google proposed HTTP header for pointing to API. If you can find or remember it, please tell me.