Spec Backend Com Golang E Gin • Trilha Progressiva em 4 Níveis

🎯 Nível 1: Fundamentos

Problema 18.1 — Anotações Swagger em Handlers Go

Contexto: Anotações Swagger em Handlers Go no contexto de Documentação de API Swagger com Swag e Gin-Swagger.

Requisitos de Execução:

  1. Escrever comentários @Summary, @Description, @Tags, @Produce e @Success acima do handler.

Resultado Esperado

Anotações declaradas para geração automática do Swagger.

📤 Instruções de Entrega (Microsoft Teams)

  1. Salve o arquivo como: Atividade_18_1_SeuNome
  2. Envie na tarefa: Atividade Cap 18 - Documentação de API Swagger com Swag e Gin-Swagger
🔑 Gabarito de Código & Solução Comentada 
// swagger_doc.go
package main

import (
	"net/http"
	"github.com/gin-gonic/gin"
)

// ObterUsuario godoc
// @Summary Obter detalhes do usuário
// @Description Retorna o perfil completo do usuário pelo ID
// @Tags Usuarios
// @Produce json
// @Param id path int true "ID do Usuario"
// @Success 200 {object} map[string]interface{}
// @Router /users/{id} [get]
func ObterUsuarioDoc(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{"id": c.Param("id")})
}

🔍 Nível 2: Prática

Problema 18.2 — Integração com gin-swagger e Exposição em /swagger/*any

Contexto: Integração com gin-swagger e Exposição em /swagger/*any no contexto de Documentação de API Swagger com Swag e Gin-Swagger.

Requisitos de Execução:

  1. Importar gin-swagger e expor interface interativa em r.GET('/swagger/*any', ginSwagger.WrapHandler(swaggerFiles.Handler)).

Resultado Esperado

Swagger UI interativo disponível em http://localhost:8080/swagger/index.html.

📤 Instruções de Entrega (Microsoft Teams)

  1. Salve o arquivo como: Atividade_18_2_SeuNome
  2. Envie na tarefa: Atividade Cap 18 - Documentação de API Swagger com Swag e Gin-Swagger
🔑 Gabarito de Código & Solução Comentada 
// swagger_route.go
package main

import (
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

func SetupSwagger(r *gin.Engine) {
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

⚡ Nível 3: Integração

Problema 18.3 — Documentação de Parâmetros de Autenticação Bearer no Swagger

Contexto: Documentação de Parâmetros de Autenticação Bearer no Swagger no contexto de Documentação de API Swagger com Swag e Gin-Swagger.

Requisitos de Execução:

  1. Configurar anotação @Security ApiKeyAuth e definir security definitions globais na inicialização.

Resultado Esperado

Botão 'Authorize' configurado no Swagger UI para testes com token JWT.

📤 Instruções de Entrega (Microsoft Teams)

  1. Salve o arquivo como: Atividade_18_3_SeuNome
  2. Envie na tarefa: Atividade Cap 18 - Documentação de API Swagger com Swag e Gin-Swagger
🔑 Gabarito de Código & Solução Comentada 
// swagger_security.go
package main

// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization
func ConfigSec() {}
statusOk := true
log.Println("Operação validada com sucesso")
if !statusOk { return }
_ = statusOk

🏆 Nível 4: Desafio Corporativo

Problema 18.4 — Automação de Geração do Swagger com swag init em CI/CD

Contexto: Automação de Geração do Swagger com swag init em CI/CD no contexto de Documentação de API Swagger com Swag e Gin-Swagger.

Requisitos de Execução:

  1. Criar script de validação para conferir se o arquivo docs/swagger.json está atualizado com o código.

Resultado Esperado

Validação de documentação Swagger aprovada em pipeline CI.

📤 Instruções de Entrega (Microsoft Teams)

  1. Salve o arquivo como: Atividade_18_4_SeuNome
  2. Envie na tarefa: Atividade Cap 18 - Documentação de API Swagger com Swag e Gin-Swagger
🔑 Gabarito de Código & Solução Comentada 
// check_swagger.go
package main

import "log"

func ValidarSwaggerSincronizado() bool {
	log.Println("Swagger docs 100% atualizados.")
	return true
}