📊 Capítulo 18: Swagger & Swag no Gin

Especialização Backend com Go & Gin Gonic

🗺️ O Fluxo de Geração do OpenAPI a partir de Comentários

flowchart LR
    GO_CODE["Código Go com Anotações Declarativas (// @Summary, // @Param)"]
    --> SWAG_CLI["Comando CLI: swag init"]
    --> DOCS_GEN["Gera pasta docs/ com swagger.json e swagger.yaml"]
    --> GIN_ROUTE["r.GET('/swagger/*', ginSwagger.WrapHandler(swaggerFiles.Handler))"]
    --> UI["Interface Interativa Swagger UI no Navegador"]

    style GO_CODE fill:#ede7f6,stroke:#512da8,stroke-width:2px
    style SWAG_CLI fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    style DOCS_GEN fill:#e1f5fe,stroke:#03a9f4,stroke-width:1.5px
    style GIN_ROUTE fill:#e8f5e9,stroke:#4caf50,stroke-width:1.5px
    style UI fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px

🎯 Slide 1: Anotando Funções Handler em Go

// @Summary Criar novo usuário
// @Description Cadastra um usuário no banco e retorna o ID gerado
// @Tags Usuarios
// @Accept json
// @Produce json
// @Param usuario body dtos.CriarUsuarioDTO true "Dados do usuário"
// @Success 201 {object} dtos.UsuarioResponseDTO
// @Failure 400 {object} gin.H "Erro de validação"
// @Router /usuarios [post]
func (h *UsuarioHandler) Criar(c *gin.Context) { ... }

🎯 Slide 2: Configurando a Rota no Gin

import (
    _ "meu-projeto/docs" // Importa os metadados gerados pelo swag
    ginSwagger "github.com/swaggo/gin-swagger"
    swaggerFiles "github.com/swaggo/files"
)

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

🎯 Slide 3: Automação no Pipeline CI/CD

• Integre o comando swag init na esteira de CI/CD para garantir que a documentação pública esteja sempre 100% sincronizada com os DTOs e rotas do repositório!