Criando api python flask com swagger

Disponibilizar dados através de api faz parte da rotina de muitos desenvolvedores. Uma ótima alternativa para agilidade de desenvolvimento e leveza é utilizar python Flask . Neste post irei demonstrar como criar uma api com python Flask e disponibilizar uma interface de documentação com swagger com pacote flask restplus.

Photo by Annie Spratt on Unsplash

Iniciando o projeto

Para iniciar podemos criar a virtual enviroment do ambiente de desenvolvimento e instalar os pacotes necessários para o projeto. Para instalar os pacotes via pip:

pip install flask
pip install flask-restplus

Depois podemos na raiz da pasta do projeto criar o arquivo run.py e uma pasta chamada app com arquivo __init__.py dentro desta pasta.

Setup inicial da app

Com o setup acima temos uma aplicação que pode rodar em multithread(aceitando requisições simultâneas) com a declaração da propriedade threaded=True na chamada de app.run() no arquivo run.py. Em __init__.py o uso da class ProxyFix do pacote werkzeug facilita a ingestão de certificado SSL na aplicação, caso sua aplicação esteja hospedada com um certificado. E já temos o inicio da criação da documentação swagger com auxilio da classe Api do pacote flask_restplus.

Criando Rotas e Documentação Swagger

Para realizar as operações CRUD irei criar uma classe que irá simular nossa base de dados na api rest. Esta classe criarei no diretório app/main/pessoa/pessoa_db.py.

Base de dados fake

Com nossa ‘base’ pronta hora de criar o recurso para controlar as requisições. Neste exemplo irei chamar de PessoaController e criar em app/main/pessoa/pessoa_controller.

Primeiramente em nosso controller irei adicionar os métodos de obtenção(get) e criação de dados(post). Na classe de controle ao definir métodos com nome get() e post(), estes métodos são compreendidos como metodos http rest get e post. A classe de controle deve herdar de Resource do pacote flask_restplus para servir como recurso na api.

Para rodar o projeto digite o comando a seguir:

python run.py

Com a implementação acima o resultado ao rodar podemos ver a documentação swagger com as rotas e modelo definidos anteriormente.

A seguir vamos implementar rotas que contem parâmetros. Como por exemplo id, que é necessário para distinguir com maior exatidão o registro que queremos manipular.

Este parâmetro padrão definido na rota é recebido como parâmetro nos métodos da classe responsável por representar este recurso. No método put() deixei como exemplo uma forma de definir parâmetros customizados quando não quiser ou for possível definir modelos. Lembrando que a forma correta de implementar o put é enviando/recebendo os dados pelo corpo da requisição.

Documentação swagger flask restplus

Possíveis erros e tratamentos

ImportError: cannot import name ‘cached_property’ from ‘werkzeug’

O erro ocorre com pacote werkzeug que por padrão nas ultimas versões do flask vem na versão 1.0.1. Alterando para versão 0.16.1 resolve esta situação.

pip install werkzeug==0.16.1

Conclusão

Existem diversos pacotes que auxiliam e facilitam implementações de funcionalidades que são necessárias na construção de APIs. Na verdade isto se aplica a todo ecossistema do python 😆 . O que torna a escrita de APIs com python flask muito divertido, fácil e pratico.

Link do github