Repolode
Enviar
swaggo

swaggo/swag

Ferramenta Go que gera documentação de API Swagger 2.0 a partir de anotações nos comentários do código-fonte Go.

Ver no GitHub
Estrelas
13,048
Forks
1,492
Issues abertas
482
Último commit
mês passado

O que é?

O Swag analisa comentários em formato específico no código Go, como os que ficam acima de funções handler e definições de structs, e gera documentação Swagger 2.0 nos arquivos swagger.json, swagger.yaml e docs.go. Os desenvolvedores adicionam anotações como @Summary, @Param, @Success e @Router acima dos handlers e executam swag init para gerar novamente a especificação.

A saída gerada pode ser disponibilizada pelo Swagger UI usando pacotes de middleware para frameworks Go populares, incluindo Gin, Echo, Fiber, net/http, chi e Hertz. Campos de structs podem receber tags com exemplos, restrições de validação, enums e substituições para tipos personalizados. O Swag também inclui o comando swag fmt, que formata os comentários com anotações.

Recursos principais

  • 01Gera especificações Swagger 2.0 em JSON, YAML e como um pacote Go de documentação.
  • 02Documenta endpoints por meio de anotações em comentários acima das funções handler em Go.
  • 03Oferece suporte a parâmetros de requisição, respostas, headers, definições de segurança e tags.
  • 04Lê tags de campos de structs para exemplos, regras de validação e enums.
  • 05Disponibiliza middleware para Gin, Echo, Fiber, net/http, chi e outros frameworks.
  • 06Inclui o comando swag fmt para formatar comentários com anotações.

Casos de uso

  • Gerar documentação de API para um serviço REST em Go sem manter manualmente um arquivo OpenAPI separado.
  • Disponibilizar uma página interativa do Swagger UI para um backend em Gin ou Echo.
  • Manter a documentação da API sincronizada com o código dos handlers durante os builds de CI.

Início rápido

  1. 1

    Instale a CLI swag com Go

    go install github.com/swaggo/swag/cmd/swag@latest
  2. 2

    Adicione anotações de API aos comentários do código-fonte Go

  3. 3

    Execute swag init na raiz do projeto que contém main.go para gerar a documentação

    swag init

Antes de usar

  • Gera apenas documentação Swagger 2.0, não OpenAPI 3.x.
  • É necessário escrever as anotações em comentários Go e gerar a documentação novamente após as alterações.

Tópicos

#golang#swagger#openapi#api-documentation#rest-api#code-generation#annotations#swagger2

Perguntas frequentes

O que é swag?
Ferramenta Go que gera documentação de API Swagger 2.0 a partir de anotações nos comentários do código-fonte Go. O Swag analisa comentários em formato específico no código Go, como os que ficam acima de funções handler e definições de structs, e gera documentação Swagger 2.0 nos arquivos swagger.json, swagger.yaml e docs.go. Os desenvolvedores adicionam anotações como @Summary, @Param, @Success e @Router acima dos handlers e executam swag init para gerar novamente a especificação.
swag é gratuito? Qual é a licença?
swag é open source sob a licença MIT. Confira os termos da licença antes de usá-lo em produtos comerciais.
swag ainda é mantido?
Atualizado nos últimos 6 meses. O último commit de swag foi em 30 de set. de 2026.
Para que posso usar swag?
Gerar documentação de API para um serviço REST em Go sem manter manualmente um arquivo OpenAPI separado. Disponibilizar uma página interativa do Swagger UI para um backend em Gin ou Echo. Manter a documentação da API sincronizada com o código dos handlers durante os builds de CI.
Como instalar swag?
Instale a CLI swag com Go: go install github.com/swaggo/swag/cmd/swag@latest Adicione anotações de API aos comentários do código-fonte Go Execute swag init na raiz do projeto que contém main.go para gerar a documentação: swag init
Onde consigo swag?
O código-fonte e as instruções de instalação estão no GitHub: https://github.com/swaggo/swag

Resumo gerado por IA a partir do README do projeto. As estatísticas do GitHub são atualizadas diariamente.

Projetos relacionados