Geração Swagger/OpenAPI para Go (Golang): guia completo

Geração Swagger/OpenAPI para Go (Golang)

Ao desenvolver serviços web em Go (Golang), uma das tarefas essenciais é criar documentação de API de alta qualidade e atualizada. Swagger (agora conhecido como OpenAPI) tornou-se o padrão da indústria para descrever interfaces RESTful. Neste artigo, abordaremos as principais ferramentas para gerar especificações OpenAPI no ecossistema Go, sua instalação, configuração e aplicação prática.

Por que o OpenAPI é importante para o desenvolvedor Go?

O OpenAPI permite criar uma descrição legível por máquina da sua API, que pode ser usada para:

• Geração automática de bibliotecas cliente em diferentes linguagens
• Criação de documentação interativa (Swagger UI)
• Validação de requisições de entrada e saída
• Teste de API com ferramentas como Postman ou Insomnia

Principais bibliotecas para geração de OpenAPI em Go

1. swaggo/swag — a escolha mais popular

A biblioteca swaggo/swag é o padrão de facto para gerar documentação Swagger em Go. Ela funciona com base em anotações nos comentários do código.

Instalação:

go get -u github.com/swaggo/swag/cmd/swaggo get -u github.com/swaggo/gin-swagger  // para o framework Gingo get -u github.com/swaggo/files

Exemplo de uso com Gin:

package main

import (    "github.com/gin-gonic/gin"    "github.com/swaggo/gin-swagger"    "github.com/swaggo/files"    _ "your-module/docs" // pacote gerado)

// @title           My API// @version         1.0// @description     Exemplo de API em Go com Swagger// @host            localhost:8080// @BasePath        /api/v1

func main() {    r := gin.Default()        r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))        r.GET("/api/v1/users", GetUsers)    r.Run(":8080")}

// GetUsers retorna a lista de usuários// @Summary      Obter lista de usuários// @Description  Retorna todos os usuários do sistema// @Tags         users// @Accept       json// @Produce      json// @Success      200  {array}   User// @Router       /users [get]func GetUsers(c *gin.Context) {    users := []User{{ID: 1, Name: "João"}}    c.JSON(200, users)}

type User struct {    ID   int    `json:"id" example:"1"`    Name string `json:"name" example:"João"`}

Após escrever o código, execute o comando:

swag init

Isso criará a pasta docs com os arquivos swagger.json e swagger.yaml.

2. go-swagger — ferramenta poderosa, porém mais complexa

go-swagger oferece não apenas a geração de documentação a partir do código, mas também o processo inverso — geração de código a partir da especificação.

Instalação:

go get -u github.com/go-swagger/go-swagger/cmd/swagger

Exemplo de geração de servidor a partir da especificação:

swagger generate server -f ./swagger.yaml -A my-api

Geração de documentação a partir do código:

// swagger:route GET /users users listUsers// Retorna a lista de usuários.// responses://   200: usersResponse

func ListUsersHandler(w http.ResponseWriter, r *http.Request) {    // implementação}

3. oapi-codegen — abordagem moderna com geração de código

A biblioteca oapi-codegen permite gerar tipos, stubs de servidor e clientes com base na especificação OpenAPI.

Instalação:

go get -u github.com/deepmap/oapi-codegen/cmd/oapi-codegen

Exemplo de uso:

Primeiro, crie o arquivo api.yaml:

openapi: "3.0.0"info:  title: My API  version: "1.0"paths:  /users:    get:      oper