Covil Do Dev

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.


Lindomar Rodrigues
Lindomar Rodrigues

Atualizado

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:

pip install fastapi

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:

pip install "uvicorn[standard]"

Criando a API

Vamos criar um arquivo chamado “main.py” que será onde vamos escrever a nossa API e vamos importar o FastAPI.

from fastapi import FastAPI

Agora vamos criar uma instância da API.

app = FastAPI()

Agora vamos criar uma rota para a API.

@app.get('/')
async def index():
    return {'message': 'Hello World'}

O código até este ponto está mais ou menos assim:

from fastapi import FastAPI

app = FastAPI()


@app.get('/')
async def index():
    return {'message': 'Hello World'}

Agora vamos rodar a API, basta ir no terminal e digitar:

uvicorn main:app --reload

Agora vamos verificar se a API está rodando, basta acessar a URL(http://127.0.0.1:8000), você verá isto:

{
  "message": "Hello World"
}

Documentação da API

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:

Imagem da documentação do FastAPI

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:

@app.get('/')
async def index(a, b):
    soma = 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:

@app.get('/')
async def index(a: int, b: int):
    soma = a + b
    return {'resultado': soma}

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:

Imagem da documentação do FastAPI

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:

from pydantic import BaseModel

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:

Imagem da documentação do FastAPI

Podemos ver que o FastAPI está documentando o retorno da API como um objeto do tipo Resposta.

Conclusão

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.

Abaixo está o código completo ao fim do artigo.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Resposta(BaseModel):
    resultado: int


@app.get('/', response_model=Resposta)
async def index(a: int, b: int):
    soma = a + b
    return {'resultado': soma}

Obrigado por visitar o blog e por ler esse artigo, se tive qualquer dúvida, ideia ou sugestão, não hesite em entrar em contato pelo meu e-mail: lindomar@covildodev.com.br