Basic API CRUD with Flask 1.0.3 & Swagger

One of the important parts for developing API is documentation. This is very crucial as when you’re developing API there’ll be big chances that you’ll work with other parties those aren’t care the detail of your code/logic but only need to know how to API works & how to use it. This way documentation comes in handy and lead to another important question how to document it? Manually document it obviously not a good idea as the API getting bigger it’ll be getting difficult to maintain. Therefore Swagger comes in handy and can be implemented in any frameworks. Swagger is my favorite tool for API documentation either when I was working in Flask or Laravel. You can adjust your API documentation along with your code logic, this way your API documentation will be more maintainable.

This article will cover how to implement swagger with flask 1.0.3. First of all let’s set a local environment to work with flask. You can read my previous article here if you need the guidance (You can skip this part if you can do it without guidance): https://medium.com/@gerrysabar/install-sqlalchemy-to-flask-1-0-2-python-3-247705e742c0 after your local environment is ready, we need to install flask-restplus (make sure you’re still in your venv environment) then execute this in root project directory:

$ pip install flask-restplus

Let’s create a file named api.py with code:

The code itself is self explanatory and you need to understand basic routing for flask especially how to access page without id such as request GET to localhost:5000 which will be pointed to method get at LogList and request get to localhost:5000/1 which will be pointed to method get at Log and send parameter id equal to 1.

Alright, now let’s test our Swagger by executing this at root project of your directory:

$ export FLASK_APP=api.py

Followed by

$ export FLASK_ENVIRONMENT=development

Last

$ flask run

Wonderful, you can see the documentation of each endpoint we created for our simple REST:

You can play around for each endpoint to see the result directly in swagger. We also can test each endpoint in terminal using CURL to access each endpoint:

$ curl -X GET http://localhost:5000/my_api/

$ curl -X POST http://localhost:5000/my_api/

$ curl -X GET http://localhost:5000/my_api/1

$ curl -X DELETE http://localhost:5000/my_api/1

$ curl -X PUT http://localhost:5000/my_api/1

But now we’ve got another thing to consider. Let’s say in PUT endpoint we need to add additional information what id is so for example another guy who is working in mobile app development and need to connect to this endpoint understand exactly the behavior of this endpoint. Therefore above put method let’s add additional code as follow:

Restart your flask application and when you check your PUT method you can see the detail we added to this endpoint as follow:

Wonderful, we just implemented basic REST API with Flask and Swagger! If you need further detail for correct HTTP Response you can visit to this link: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes and you also can visit this link for further swagger documentation in flask https://flask-restplus.readthedocs.io/en/stable/swagger.html. If you want to connect this REST app to database you can read this article.