swag

🌍 English ∙ 简体中文 ∙ Português

Swag converte anotações Go para Documentação Swagger 2.0. Criámos uma variedade de plugins para populares Go web frameworks. Isto permite uma integração rápida com um projecto Go existente (utilizando a Swagger UI).

Conteúdo

• Começando
• Estruturas Web Suportadas
• Como utilizá-lo com Gin
• O formatador de swag
• Estado de Implementação
• Formato dos comentários declarativos
  • Informações Gerais API
  • Operação API
  • Segurança
• Exemplos
  • Descrições em múltiplas linhas
  • Estrutura definida pelo utilizador com um tipo de matriz
  • Declaração de estruturação de funções
  • Composição do modelo em resposta
  • Adicionar um cabeçalho em resposta
  • Utilizar parâmetros de caminhos múltiplos
  • Exemplo de valor de estrutura
  • Schema Exemplo do corpo
  • Descrição da estrutura
  • Usar etiqueta do tipo swaggertype para suportar o tipo personalizado
  • Utilizar anulações globais para suportar um tipo personalizado
  • Use swaggerignore tag para excluir um campo
  • Adicionar informações de extensão ao campo de estruturação
  • Renomear modelo a expor
  • Como utilizar as anotações de segurança
  • Adicionar uma descrição para enumerar artigos
  • Gerar apenas tipos de ficheiros de documentos específicos
  • Como usar tipos genéricos
• Sobre o projecto

Começando

1. Adicione comentários ao código-fonte da API, consulte Formato dos comentários declarativos.

2. Descarregue o swag utilizando:

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

Para construir a partir da fonte é necessário Go (1.19 ou mais recente).

Ou descarregar um binário pré-compilado a partir da página de lançamento.

1. Executar swag init na pasta raiz do projecto que contém o ficheiro main.go. Isto irá analisar os seus comentários e gerar os ficheiros necessários (pasta docs e docs/docs.go).

swag init

Certifique-se de importar os docs/docs.go gerados para que a sua configuração específica fique "init" ed. Se as suas anotações API gerais não viverem em main.go, pode avisar a swag com a bandeira -g.

swag init -g http/api.go

1. (opcional) Utilizar o formato swag fmt no comentário SWAG. (Por favor, actualizar para a versão mais recente)

swag fmt

swag cli

swag init -h
NOME:
   swag init - Criar docs.go

UTILIZAÇÃO:
   swag init [opções de comando] [argumentos...]

OPÇÕES:
   --quiet, -q Fazer o logger ficar quiet (por padrão: falso)
   --generalInfo valor, -g valor Go caminho do ficheiro em que 'swagger general API Info' está escrito (por padrão: "main.go")
   --dir valor, -d valor Os directórios que deseja analisar, separados por vírgulas e de informação geral devem estar no primeiro (por padrão: "./")
   --exclude valor Excluir directórios e ficheiros ao pesquisar, separados por vírgulas
   -propertyStrategy da estratégia, -p valor da propriedadeEstratégia de nomeação de propriedades como snakecase,camelcase,pascalcase (por padrão: "camelcase")
   --output de saída, -o valor directório de saída para todos os ficheiros gerados(swagger.json, swagger.yaml e docs.go) (por padrão: "./docs")
   --outputTypes valor de saídaTypes, -- valor de saída Tipos de ficheiros gerados (docs.go, swagger.json, swagger.yaml) como go,json,yaml (por padrão: "go,json,yaml")
   --parseVendor ParseVendor Parse go files na pasta 'vendor', desactivado por padrão (padrão: falso)
   --parseInternal Parse go ficheiros em pacotes internos, desactivados por padrão (padrão: falso)
   --generatedTime Gerar timestamp no topo dos docs.go, desactivado por padrão (padrão: falso)
   --parteDepth value Dependência profundidade parse (por padrão: 100)
   --templateDelims value, --td value fornecem delimitadores personalizados para a geração de modelos Go. O formato é leftDelim,rightDelim. Por exemplo: "[[,]]"
   ...

   --help, -h mostrar ajuda (por padrão: falso)

swag fmt -h
NOME:
   swag fmt - formato swag comentários

UTILIZAÇÃO:
   swag fmt [opções de comando] [argumentos...]

OPÇÕES:
   --dir valor, -d valor Os directórios que pretende analisar, separados por vírgulas e de informação geral devem estar no primeiro (por padrão: "./")
   --excluir valor Excluir directórios e ficheiros ao pesquisar, separados por vírgulas
   --generalInfo value, -g value Go file path in which 'swagger general API Info' is written (por padrão: "main.go")
   --ajuda, -h mostrar ajuda (por padrão: falso)

Estruturas Web Suportadas

• gin
• echo
• buffalo
• net/http
• gorilla/mux
• go-chi/chi
• flamingo
• fiber
• atreugo
• hertz

Como utilizá-lo com Gin

Encontrar o código fonte de exemplo aqui.

1. Depois de utilizar swag init para gerar os documentos Swagger 2.0, importar os seguintes pacotes:

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files

1. Adicionar Informações Gerais API anotações em código main.go:

// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html

// @host      localhost:8080
// @BasePath  /api/v1

// @securityDefinitions.basic  BasicAuth

// @externalDocs.description  OpenAPI
// @externalDocs.url          https://swagger.io/resources/open-api/
func main() {
    r := gin.Default()

    c := controller.NewController()

    v1 := r.Group("/api/v1")
    {
        accounts := v1.Group("/accounts")
        {
            accounts.GET(":id", c.ShowAccount)
            accounts.GET("", c.ListAccounts)
            accounts.POST("", c.AddAccount)
            accounts.DELETE(":id", c.DeleteAccount)
            accounts.PATCH(":id", c.UpdateAccount)
            accounts.POST(":id/images", c.UploadAccountImage)
        }
    //...
    }
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    r.Run(":8080")
}
//...

Além disso, algumas informações API gerais podem ser definidas de forma dinâmica. O pacote de código gerado docs exporta a variável SwaggerInfo que podemos utilizar para definir programticamente o título, descrição, versão, hospedeiro e caminho base. Exemplo utilizando Gin:

package main

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

    "./docs" // docs is generated by Swag CLI, you have to import it.
)

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
func main() {

    // programmatically set swagger info
    docs.SwaggerInfo.Title = "Swagger Example API"
    docs.SwaggerInfo.Description = "This is a sample server Petstore server."
    docs.SwaggerInfo.Version = "1.0"
    docs.SwaggerInfo.Host = "petstore.swagger.io"
    docs.SwaggerInfo.BasePath = "/v2"
    docs.SwaggerInfo.Schemes = []string{"http", "https"}

    r := gin.New()

    // use ginSwagger middleware to serve the API docs
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    r.Run()
}

1. Adicionar Operação API anotações em código controller

package controller

import (
    "fmt"
    "net/http"
    "strconv"

    "github.com/gin-gonic/gin"
    "github.com/swaggo/swag/example/celler/httputil"
    "github.com/swaggo/swag/example/celler/model"
)

// ShowAccount godoc
// @Summary      Show an account
// @Description  get string by ID
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        id   path      int  true  "Account ID"
// @Success      200  {object}  model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts/{id} [get]
func (c *Controller) ShowAccount(ctx *gin.Context) {
  id := ctx.Param("id")
  aid, err := strconv.Atoi(id)
  if err != nil {
    httputil.NewError(ctx, http.StatusBadRequest, err)
    return
  }
  account, err := model.AccountOne(aid)
  if err != nil {
    httputil.NewError(ctx, http.StatusNotFound, err)
    return
  }
  ctx.JSON(http.StatusOK, account)
}

// ListAccounts godoc
// @Summary      List accounts
// @Description  get accounts
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        q    query     string  false  "name search by q"  Format(email)
// @Success      200  {array}   model.Account
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /accounts [get]
func (c *Controller) ListAccounts(ctx *gin.Context) {
  q := ctx.Request.URL.Query().Get("q")
  accounts, err := model.AccountsAll(q)
  if err != nil {
    httputil.NewError(ctx, http.StatusNotFound, err)
    return
  }
  ctx.JSON(http.StatusOK, accounts)
}
//...

swag init

1. Execute a sua aplicação, e navegue para http://localhost:8080/swagger/index.html. Verá os documentos Swagger 2.0 Api, como mostrado abaixo:

O formatador de swag

Os Swag Comments podem ser formatados automaticamente, assim como 'go fmt'. Encontre o resultado da formatação aqui.

Usage:

swag fmt

Exclude folder：

swag fmt -d ./ --exclude ./internal

Ao utilizar swag fmt, é necessário assegurar-se de que tem um comentário doc para a função a fim de assegurar uma formatação correcta. Isto deve-se ao swag fmt que traça comentários swag com separadores, o que só é permitido após um comentário doc padrão.

Por exemplo, utilizar

// ListAccounts lists all existing accounts
//
//  @Summary      List accounts
//  @Description  get accounts
//  @Tags         accounts
//  @Accept       json
//  @Produce      json
//  @Param        q    query     string  false  "name search by q"  Format(email)
//  @Success      200  {array}   model.Account
//  @Failure      400  {object}  httputil.HTTPError
//  @Failure      404  {object}  httputil.HTTPError
//  @Failure      500  {object}  httputil.HTTPError
//  @Router       /accounts [get]
func (c *Controller) ListAccounts(ctx *gin.Context) {

Estado de Implementação

Documento Swagger 2.0

• [x] Estrutura básica
• [x] Hospedeiro API e Caminho Base
• [x] Caminhos e operações
• [x] Descrição dos parâmetros
• [x] Descrever o corpo do pedido
• [x] Descrição das respostas
• [x] Tipos MIME
• [x] Autenticação
• [x] Autenticação básica
• [x] Chaves API
• [x] Acrescentar exemplos
• [x] Carregamento de ficheiros
• [x] Enums
• [x] Operações de Agrupamento com Etiquetas
• Extensões Swagger

Formato dos comentários declarativos

Informações Gerais API

Exemplo [celler/main.go](https://github.com/swaggo/swag/blob/master/exampl