You don’t believe me, look at this.
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
Lets get Started
- Open console or bash
# pip install flask_swagger_ui
- Open your
app.pywhere you instantiated Flask and add to the top
from flask_swagger_ui import get_swaggerui_blueprint
- Add a folder to the root of your project and name it
4. Create a new file in it and name it
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
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 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
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
tags elements to your
11. Force refresh browser to see the new
12. Now to describe the
paths, and first I will add a
get request to the
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
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
The finished product
All the code in this article is at
Contribute to Sean-Bradley/Seans-Python3-Flask-Rest-Boilerplate development by creating an account on GitHub.
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.