Fazendo uma API com documentação automática em Python utilizando FastAPI
FastAPI é um framework extremamente moderno para desenvolvimento de API 's em Python. Tem uma estrutura simples pensada para otimizar o desenvolvimento de soluções prontas para produção com as melhores práticas. Neste artigo iremos aprender como fazer uma API com documentação de forma "automática" utilizando FastAPI.
Antes de iniciar o tutorial, vamos ver as principais características do FastAPI e porque é esse é o framework queridinho do momento:
Oferece um alto desempenho, em grande parte pois tem como bases o Starlette e o pydantic.
É baseado em padrões abertos de API, como AbraAPI e JSON-Schema.
Fornece uma documentação interativa de forma automática.
Por utilizar pydantic, reduz bastante a possibilidade de erros humanos.
Instalando o FastAPI
Antes de iniciar o desenvolvimento da API, precisamos preparar o ambiente instalando as bibliotecas que vamos utilizar.
Para instalar o FastAPI, basta utilizar o comando:
Também vamos precisar instalar o uvicorn para rodar a API, o uvicorn é um servidor ASGI que será o responsável por rodar a API, para instalar basta executar o comando abaixo:
Vamos criar um arquivo chamado "main.py" que será onde vamos escrever a nossa API e vamos importar o FastAPI.
Agora vamos criar uma instância da API.
Agora vamos criar uma rota para a API.
O código até este ponto está mais ou menos assim:
Agora vamos rodar a API, basta ir no terminal e digitar:
Agora vamos verificar se a API está rodando, basta acessar a URL(http://127.0.0.1:8000), você verá isto:
Uma das maiores vantagens de utilizar o FastAPI é que muita coisa da documentação é abstraida de forma automática, acessando a url (http://127.0.0.1:8000/docs) você verá a documentação da API, por enquanto será algo semelhante a isso:
Porém podemos melhorar, e é exatamente isso que vamos fazer a seguir.
Adicionando tipagem na API
Para adicionar tipagem na API, primeiro vamos alterar o nosso endpoint, para que ele receba dois parâmetros:
async def index(a, b):
return {'resultado': soma}
Acessando o endpoint com os parâmetros da seguinte forma http://127.0.0.1:8000/?a=1&b=2 você verá algo estranho, semelhante a isso:
"resultado": "12"
Você provavelmente entendeu oque aconteceu, esse é um erro muito comum e acontece porque o dado não foi interpretado como inteiro e sim como texto.
Para resolver isso, vamos adicionar um parâmetro de tipagem na API, para que os parâmetros seja interpretado como int:
async def index(a: int, b: int):
Agora acessando o endpoint veremos que o resultado é o seguinte:
"resultado": 3
Agora vamos verificar se o FastAPI está documentando isso corretamente, acessando o endpoint de docs(http://127.0.0.1:8000/docs) você verá algo semelhante a isso:
Podemos ver que o FastAPI está documentando os dois parâmetros como inteiro.
Tipando e documentando o retorno da API
Para documentar o formato da saída podemos passar o parâmetro response_model, para isso vamos primeiro importar o modelo base do pydantic:
Agora podemos criar um modelo de resposta, para isso vamos criar um modelo de resposta da seguinte forma:
class Resposta(BaseModel):
resultado: int
Agora vamos alterar o nosso endpoint, para que ele retorne o modelo de resposta:
@app.get('/', response_model=Resposta)
Agora acessando o endpoint veremos que o resultado é continua o mesmo, mas quando vamos olhar a documentação da API, na aba schema veremos o seguinte:
Podemos ver que o FastAPI está documentando o retorno da API como um objeto do tipo Resposta.
Ao final do artigo podemos ver que o FastAPI atualmente é um ótimo framework para desenvolvimento de api 's, e na minha humilde opinião é questão de tempo até substituir quase completamente o Django e o Flask nesse quesito de criar API' s.
Além desse ponto da documentação automática, outro ponto importante é que o FastAPI é um framework assíncrono, pretendo fazer um artigo mais completo(e de leitura mais chata rs) no futuro onde vou abordar esse assunto.
Como pythonista mais raiz e cheio de vícios eu ainda tenho um pouco de dificuldade em adotar tipagem em todos os meus códigos, mas utilizando o FastAPI é notável como isso é um ferramenta poderosa, e usada nos locais corretos podem economizar muito tempo fazendo debug.