4 ms·

SOAP is a nightmare, but my experience with Swagger has not been so far. I used flask and marshmallow to create an API and a plug-in to generate the swagger sch

SOAP is a nightmare, but my experience with Swagger has not been so far. I used flask and marshmallow to create an API and a plug-in to generate the swagger scheme from it. It just worked. I see it more as an interactive documentation generator than some kind of dynamic API pipe dream.

michaelsbradley 9y ago
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/
- dreamfactored 9y ago
  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
  - michaelsbradley 9y ago
    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.
mixmastamyk 9y ago
Have a blog post handy? Need to make a flask rest api and would like it as automatic as possible.
- michaelsbradley 9y ago
  Swagger Editor[1] can spit out the skeleton of a Flask based server from an OpenAPI 2.0 specification. The generated code makes use of the Connexion famework[2]. Paste your specification into the editor, fix it if it's not valid, open the "Generate Server" dropdown in the top menu, and select "python-flask". [1] http://editor.swagger.io/ http://editor.swagger.io/ [2] https://github.com/zalando/connexion/ https://github.com/zalando/connexion/
- luhn 9y ago
  Don't have a blog post for you, but I'm pretty sure he's utilitizing Flask-APISpec (https://github.com/jmcarp/flask-apispec https://github.com/jmcarp/flask-apispec). I've been eying it for a while.

michaelsbradley 9y ago

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/

dreamfactored 9y ago
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
- michaelsbradley 9y ago
  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.

mixmastamyk 9y ago

Have a blog post handy? Need to make a flask rest api and would like it as automatic as possible.

michaelsbradley 9y ago
Swagger Editor[1] can spit out the skeleton of a Flask based server from an OpenAPI 2.0 specification. The generated code makes use of the Connexion famework[2]. Paste your specification into the editor, fix it if it's not valid, open the "Generate Server" dropdown in the top menu, and select "python-flask". [1] http://editor.swagger.io/ http://editor.swagger.io/ [2] https://github.com/zalando/connexion/ https://github.com/zalando/connexion/
luhn 9y ago
Don't have a blog post for you, but I'm pretty sure he's utilitizing Flask-APISpec (https://github.com/jmcarp/flask-apispec https://github.com/jmcarp/flask-apispec). I've been eying it for a while.