Swagger and Flask Tutorial

Introduction

• API documentation is important.
• Coding to Interfaces and Separation of Concerns remain fundamental design patterns
• Any project involving a great deal of source code and multiple developers will likely fail without proper attention to this design
• Exposing Functionality is important
• This conveys and demonstrates progress 
• In a proper SOA design, functionality is exposed as a series of internal business processes
• Business Processes are APIs
• By using Swagger to document the APIs we get an auto-generated user interface that both documents and helps a (somewhat technical) user explore the dialog functionality
• Any Tester or Business Analyst role should have the skill to navigate a Swagger-generated API, view the documentation, and explore a variety of I/O possibilities

API Documentation in Swagger

You can download swagger locally, but I find it just as easy to use the remote site.

http://editor.swagger.io

Once there, you can create your markup.  There are some useful tutorials in the references section.

Once you've defined your markup, then use the Generate Server option:

Generate a Python Flask app from the YAML markup

This generates a Python Flask application from the YAML markup.

Fixing the Generated Code

There were a few manual fixes I had to make consistently each time I regenerated the flask app.

1. Each method was generated into a separate python file (<name>_controller.py).  There was a casing issue that I had to correct. 
   
   The swagger.yaml file had this
   operationId: "controllers.Occurences_controller.ups_global_get"
   
   and I had to change that to this:
   operationId: "controllers.occurences_controller.ups_global_get"
   
   in order to correspond to the actual casing of the python file.
2. Likewise, the generated code was initially configured to run the swagger UI on port 80 and the operations on port 8080. 
   
   This caused some trouble, as the endpoint operation couldn't figure out which port to use when.
   
   It became a lot easier when I changed this line from
   host: "localhost"
   to
   host: "localhost:5000"
   and alter app.py to run on 5000 as well:
   

   app.run(port=5000)

3. The generated code needs some changing:

 I'm using Python 2.7.12 :: Anaconda 4.1.1 (x86_64) on OS X 10.11.6 (15G1108).

Running the App

By going to this URL

http://localhost:5000/dialog/ui/

I saw this screen

I could then expand operations, find the single operation I had documented:

and execute a simple test.

References

1. Swagger Tutorial
2. Online Swagger Editor