📊 Capítulo 18: OpenAPI & Swagger UI

Especialização Backend com Python & FastAPI

🗺️ A Geração Automática do OpenAPI Spec 3.1

flowchart LR
    PY_CODE["Código Python + Schemas Pydantic + Docstrings"]
    --> FASTAPI["FastAPI Metadata Compiler"]
    --> OPENAPI_JSON["openapi.json (Especificação OpenAPI 3.1)"]
    OPENAPI_JSON --> SWAGGER["Swagger UI (/docs)\n- Teste Interativo de Endpoints"]
    OPENAPI_JSON --> REDOC["ReDoc UI (/redoc)\n- Documentação Técnica de Leitura"]
    OPENAPI_JSON --> CLIENTS["Geração de SDKs Frontend (TypeScript / Swift)"]

    style PY_CODE fill:#ede7f6,stroke:#512da8,stroke-width:2px
    style FASTAPI fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style OPENAPI_JSON fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    style SWAGGER fill:#e1f5fe,stroke:#03a9f4,stroke-width:1.5px
    style REDOC fill:#c8e6c9,stroke:#2e7d32,stroke-width:1.5px
    style CLIENTS fill:#e0f2f1,stroke:#00897b,stroke-width:1.5px

🎯 Slide 1: Customizando Metadados Globais da API

app = FastAPI(
    title="E-Commerce Enterprise API",
    description="API de alta performance para processamento de pagamentos e pedidos.",
    version="1.0.0",
    contact={
        "name": "Equipe de Engenharia Backend",
        "email": "backend@empresa.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
    openapi_tags=[
        {"name": "Autenticação", "description": "Endpoints de login e tokens"},
        {"name": "Produtos", "description": "Catálogo de mercadorias"}
    ]
)

🎯 Slide 2: Enriquecendo Endpoints com Exemplos

@router.post(
    "/produtos",
    summary="Criar um novo produto no catálogo",
    description="Valida se o SKU já existe e cadastra o produto com preço positivo.",
    response_description="Produto cadastrado com sucesso",
    responses={
        400: {"description": "Dados de payload inválidos"},
        409: {"description": "SKU já cadastrado anteriormente"}
    }
)
async def criar_produto(payload: ProdutoCreate):
    ...

🎯 Slide 3: Desabilitando Docs em Produção

• Segurança: Em ambientes corporativos de produção, é comum desativar as rotas públicas de documentação:

  app = FastAPI(
    docs_url=None if settings.IS_PROD else "/docs",
    redoc_url=None if settings.IS_PROD else "/redoc",
    openapi_url=None if settings.IS_PROD else "/openapi.json"
  )