The new “Swagger” UI for our docs for the CHT REST api is now live on the docs site!
This new documentation format is easier to read/browse thanks to the consistency and features of Swagger. It is also much easier to maintain and keep up-to-date because it is built automatically from configuration tracked in cht-core.
In cht-core we use the OpenAPI specification to capture the details of each REST endpoint. We store those details in comments close to the code for the endpoint so it can be easily updated when the code changes. Then, an automated pipeline will publish the updated OpenAPI specification for the CHT endpoints whenever a commit is merged to master. The newly published spec is immediately reflected on the docs page without requiring a separate PR to the cht-docs repo. 
See this documentation page for more details on the process.