Fazendo uma API com documentação automática em Python 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:

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:

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:

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:

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}