Re:Swagger is now the OpenAPI Specification
by dreamfactored on Monday October 23, 2017 @04:49PM
(#15536820)
Unless I misunderstood your approach I think working from what a consumer would like > what the server produces is forwards not backwards when it comes to API design
Re:Swagger is now the OpenAPI Specification
by michaelsbradley on Monday October 23, 2017 @05:25PM
(#15537061)
In this case "what the server produces" was already defined and I was not given a mandate to change it prior to v1.0. Also, the server implementation was a bit messy and mostly undocumented.
So I worked "backwards" in the sense that I put myself in the perspective of a consumer of the information it serves and then documented the server's behavior with OpenAPI. Certainly, in the process I made much reference to the Python code used to implement the server's endpoints, but some of the endpoints' quirks were discovered in the process of precisely describing (with OpenAPI) their inputs and outputs.
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/
[2] https://paw.cloud/client
[3] https://github.com/OAI/OpenAPI-Specification/blob/master/ver...
[4] http://www.yaml.org/
[5] https://github.com/yoshiki/yaml-mode
[6] http://json-schema.org/
[7] https://github.com/Rebilly/ReDoc/