Your Python Flask API is Nothing Without Swagger UI.

You don’t believe me, look at this.

Much better.

Once you’ve created the Swagger UI layer, your API documentation is much more presentable to pass onto your line managers, colleagues and third party consumers.

This is a Python Flask Specific implementation. It is expected that you already have at least a minimal Flask REST API with a few end points ready to be documented. If not, you can get the code from here, https://github.com/Sean-Bradley/Seans-Python3-Flask-Rest-Boilerplate
and then run # pip install -r requirements.txt

  1. Open console or bash
    # pip install flask_swagger_ui
  2. Open your app.py where you instantiated Flask and add to the top
    from flask_swagger_ui import get_swaggerui_blueprint
  3. Add a folder to the root of your project and name it static.
Showing new static folder

4. Create a new file in it and name it swagger.json

With swagger.json file

5. Add some Swagger specific blueprint code after you instantiate Flask

In the above code, a URI is created at the /swagger endpoint, and it returns a file called /swagger.json which will be parsed inside a self hosted Swagger-UI front end.

6. Add the minimum JSON to the swagger.json file so that we can atleast test it’s working.

7. Start your app

# python app.py

8. And visit

http://127.0.0.1:5000/swagger/

And you should see this below.

Note that it says, ‘No operations defined in spec’. We will continue this now.

9. Now to add the components and schemas for your spec so your swagger.json looks like this.

And when you refresh, the Swagger-UI will look like this. Looks amazing already.

swagger.json with schemas added

The swagger.json file above describes the structure of messages the API will return in it’s responses. eg, an id in the API responses will be named uuid, and be a string. The bookRequestPostBody describes the JSON of the response when you post a new bookRequest to the API. You can look at this in your own time to see the links between the API code, the swagger.json and the Swagger-UI interface. All the code is hosted at https://github.com/Sean-Bradley/Seans-Python3-Flask-Rest-Boilerplate

10. Now add servers and tags elements to your swagger.json

11. Force refresh browser to see the new server and tags elements

12. Now to describe the paths, and first I will add a get request to the swagger.json spec.

In the above code, you can see a new paths element with a get request which describes the response with its code and schema. We did schemas in step 9.

13. Force refresh your browser to see the new get request in the Swagger-UI

Press the light blue line for GET, press the try it button, then press execute, and you will get the response as above. See the response body section and headers. This is cool.

14. See my complete swagger.json to see more examples of CRUD type endpoints such as post, get/{id}, put{id} and delete{id}

The finished product

All the code in this article is at

and there is an accompanying video tutorial at

Thanks for reading, please clap if you would like me to do more tutorials. There are millions of things I can write tutorials about.

Developer of real time, low latency, high availability, asynchronous, multi threaded, remotely managed, fully automated and monitored solutions.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store