I was recently tasked with tightening up and documenting an HTTP API I didn't write. The original authors used Django and Django REST Framework[1], but lacking

I was recently tasked with tightening up and documenting an HTTP API I didn't write. The original authors used Django and Django REST Framework[1], but lacking deep experience with either, mostly rolled their own functions for requests, responses, and communications with the back-end databases and other external data sources. Rather than attempting to sort it out, I used Paw[2] to get my arms around the API from a consumer's POV, had Paw generate a skeleton of an OpenAPI 2.0 (Swagger 2.0)[3] description, converted it to YAML[4] and began putting flesh on the bones manually (yaml-mode[5] in Emacs is pretty decent). In the process of covering all the bases with precise req/res definitions and examples (yay, JSON Schema![6]), I uncovered a lot of corner cases in the API's functionality and made sure they were handled properly or at least documented well. I co-located the openapi.yaml file and ReDoc[7] with the API, and now it has beautiful web-based documentation. It also has JS, Python and curl code samples for all endpoints, generated with Paw and included in the YAML formatted description. ReDoc displays them nicely, with syntax highlighting. In short, even though I worked "backwards" — matching the OpenAPI description to the functionality — it was a fruitful exercise and the results seem pretty good. Not to mention, all the above is readily tracked with git and can live right next to the server's source code... compared to, say, an equivalent documentation effort accomplished with MS Word. [1] http://www.django-rest-framework.org/ http://www.django-rest-framework.org/ [2] https://paw.cloud/client https://paw.cloud/client [3] https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md https://github.com/OAI/OpenAPI-Specification/blob/master/ver... [4] http://www.yaml.org/ http://www.yaml.org/ [5] https://github.com/yoshiki/yaml-mode https://github.com/yoshiki/yaml-mode [6] http://json-schema.org/ http://json-schema.org/ [7] https://github.com/Rebilly/ReDoc/ https://github.com/Rebilly/ReDoc/