mozilla
Improve quality of OpenAPI Spec information
We should create / publish this explicitly as part of the API. It should be returned as JSON since it's meant to be used to generate documentation / tooling.
Something like this? https://normandy.cdn.mozilla.net/api/docs/?format=openapi . These are machine generated from the code via Swagger. They could probably use some work, but they seem to be fairly complete to me.
One interesting property of the generation of these is that the readonly servers don't document the write APIs. Those are only visible on the openapi specs generated by the read-write servers (behind VPN).
You can however see those APIs in the docs for the dev server: https://normandy.dev.mozaws.net/api/docs/?format=openapi . This works because the dev server doesn't have the read-only/read-write split that stage and prod do, so the public server is a read-write server (still requires auth).
Oh neat. My preference is to write the spec first then build the API but this is fine for now. How can we populate the descriptions / add more documentation?
The prose parts of that come from the python docstrings and other in-code documentation. For example, /__version__ has a description of "Return data for developers and users to inspect the state of a server.", which comes from the docstring of the view associated with that endpoint, in normandy/health/api/views.py