News for hackers. Stuff that matters.
Re:Swagger is now the OpenAPI Specification by deckar01 on Monday October 23, 2017 @01:57PM (#15535325)
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.

Re:Swagger is now the OpenAPI Specification by michaelsbradley on Monday October 23, 2017 @02:17PM (#15535512)
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/

[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/

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.

Re:Swagger is now the OpenAPI Specification by mixmastamyk on Monday October 23, 2017 @02:26PM (#15535603)
Have a blog post handy? Need to make a flask rest api and would like it as automatic as possible.
Re:Swagger is now the OpenAPI Specification by michaelsbradley on Monday October 23, 2017 @02:29PM (#15535644)
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/

[2] https://github.com/zalando/connexion/

Re:Swagger is now the OpenAPI Specification by luhn on Monday October 23, 2017 @04:10PM (#15536545)
Don't have a blog post for you, but I'm pretty sure he's utilitizing Flask-APISpec (https://github.com/jmcarp/flask-apispec). I've been eying it for a while.