6

I was looking at the OAS and can see where it lists the recommended file name as being openapi.json but I have two questions:

  1. There evidentially isn't a standard location to put it in but is there a de facto standard that people seem to follow? Like is the assumption that the most "normal" place to make it accessible under /openapi.json ?

  2. Why is this left out of the spec and why is even just the document name only recommended instead of being required? Isn't part of the point of this to make it discoverable? Seems like relocating the OpenAPI document cuts against that by giving you something you just kind of have to know. Is there an advantage to leaving it out though?

Bratchley
  • 460
  • 6
  • 17
  • Related (or duplicate): [OpenAPI or swagger.json auto discovery](https://stackoverflow.com/q/41660658/113116). Related discussions in the OpenAPI Specification repository: [RFC 5785 conventions & suggested OpenAPI document locations](https://github.com/OAI/OpenAPI-Specification/issues/1851), [Linking API to OpenAPI and documentation](https://github.com/OAI/OpenAPI-Specification/issues/724), [OpenAPI or swagger.json auto discovery](https://github.com/OAI/OpenAPI-Specification/issues/864) – Helen Aug 31 '20 at 20:07
  • The SO question looks to be outdated (the original poster appears to have edited to essentially say to not use the answer). Reading the github issues though this seems like an open issue currently. I've seen two different mentions of putting it in whatever the base dir of the API's happens to be (i.e `/api`, `/v2`, etc) and I'm seeing mention of apis.json in the site's `/` directory.So I guess I kind of have the answer to my #2 but my #1 (if I'm right) appears to be undecided by the community. – Bratchley Aug 31 '20 at 20:27
  • one of the other comments appears to also reference RFC8631 which isn't standardized (purely "informational" apparently) and at the very least my flask restplus api doesn't set this `service-desc` response header. – Bratchley Aug 31 '20 at 20:46

0 Answers0