Como Configurar o Swagger no FastAPI para Documentação de APIs

O que é Swagger e por que usá-lo?

Swagger é um conjunto de ferramentas que permite documentar, testar e visualizar APIs REST de forma interativa. Ele facilita a exploração dos endpoints sem a necessidade de clientes HTTP externos, como Postman.

No FastAPI, o Swagger já vem embutido por padrão, permitindo gerar uma documentação detalhada automaticamente sem precisar de bibliotecas externas.

Passo 1: Instalando o FastAPI e o Uvicorn

Para começar, instale o FastAPI e o servidor Uvicorn com o seguinte comando:

pip install fastapi uvicorn

Passo 2: Criando um Projeto FastAPI

Crie um arquivo chamado main.py e adicione o seguinte código:

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

@app.get("/")
def root():
    return {"message": "Bem-vindo à API"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

# Customizando o OpenAPI para SEO
@app.get("/openapi.json")
def custom_openapi():
    return get_openapi(
        title="Minha API FastAPI",
        version="1.0.0",
        description="Documentação da API com SEO",
        routes=app.routes,
    )

Passo 3: Acessando a Documentação da API

Agora, inicie o servidor executando:

uvicorn main:app --reload

Após iniciar, acesse os seguintes links para visualizar a documentação:

• Swagger UI: http://127.0.0.1:8000/docs
• Redoc UI: http://127.0.0.1:8000/redoc

Benefícios do Swagger no FastAPI

✅ Documentação interativa e gerada automaticamente.

✅ Facilidade para testar endpoints sem ferramentas externas.

✅ Melhor comunicação entre desenvolvedores e consumidores da API.

✅ Melhor indexação nos motores de busca.

Perguntas Frequentes (FAQ)

1. O que é o Swagger no FastAPI?

No FastAPI, Swagger é a interface gráfica gerada automaticamente para visualizar e testar os endpoints da API.

2. Preciso instalar algo para usar o Swagger no FastAPI?

Não. O FastAPI já inclui o Swagger e o Redoc por padrão.

3. Como posso proteger a documentação da API?

Você pode restringir o acesso à documentação adicionando um sistema de autenticação:

from fastapi import Depends
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.get("/docs", dependencies=[Depends(oauth2_scheme)])
def protected_docs():
    return {"message": "Você precisa estar autenticado para acessar esta documentação."}

Isso impedirá que usuários não autenticados acessem os endpoints do Swagger.

Conclusão

Agora você configurou corretamente o Swagger no FastAPI . Isso melhora a experiência de desenvolvimento, facilita testes da sua API.

🔹 Gostou do tutorial? Deixe seu comentário e compartilhe com outros desenvolvedores! 🚀