swag
v1.16.4
? Inglês ∙ 简体中文 ∙ Português
Swag Converts GO Anotações GO para Swagger Documentation 2.0. Criamos uma variedade de plugins para estruturas populares da Web Go. Isso permite que você se integre rapidamente a um projeto GO existente (usando a interface do usuário do Swagger).
Adicione comentários ao seu código -fonte da API, consulte o formato de comentários declarativos.
Instale os ganhos usando:
go install github.com/swaggo/swag/cmd/swag@latestPara construir a partir da fonte, você precisa ir (1.19 ou mais recente).
Como alternativa, você pode executar a imagem do Docker:
docker run --rm -v $( pwd ) :/code ghcr.io/swaggo/swag:latestOu faça o download de um binário pré-compilado na página de lançamento.
swag init na pasta raiz do projeto, que contém o arquivo main.go Isso analisará seus comentários e gerará os arquivos necessários (pasta docs e docs/docs.go ). swag init Certifique -se de importar os docs/docs.go para que sua configuração específica seja init 'ed. Se suas anotações gerais de API não morarem em main.go , você poderá informar o swag com -g sinalizador.
import _ "example-module-name/docs" swag init -g http/api.goswag fmt . (Atualize para a versão mais recente) swag fmtswag init -h
NAME:
swag init - Create docs.go
USAGE:
swag init [command options] [arguments...]
OPTIONS:
--quiet, -q Make the logger quiet. (default: false)
--generalInfo value, -g value Go file path in which ' swagger general API Info ' is written (default: " main.go " )
--dir value, -d value Directories you want to parse,comma separated and general-info file must be in the first one (default: " ./ " )
--exclude value Exclude directories and files when searching, comma separated
--propertyStrategy value, -p value Property Naming Strategy like snakecase,camelcase,pascalcase (default: " camelcase " )
--output value, -o value Output directory for all the generated files(swagger.json, swagger.yaml and docs.go) (default: " ./docs " )
--outputTypes value, --ot value Output types of generated files (docs.go, swagger.json, swagger.yaml) like go,json,yaml (default: " go,json,yaml " )
--parseVendor Parse go files in ' vendor ' folder, disabled by default (default: false)
--parseDependency, --pd Parse go files inside dependency folder, disabled by default (default: false)
--parseDependencyLevel, --pdl Enhancement of ' --parseDependency ' , parse go files inside dependency folder, 0 disabled, 1 only parse models, 2 only parse operations, 3 parse all (default: 0)
--markdownFiles value, --md value Parse folder containing markdown files to use as description, disabled by default
--codeExampleFiles value, --cef value Parse folder containing code example files to use for the x-codeSamples extension, disabled by default
--parseInternal Parse go files in internal packages, disabled by default (default: false)
--generatedTime Generate timestamp at the top of docs.go, disabled by default (default: false)
--parseDepth value Dependency parse depth (default: 100)
--requiredByDefault Set validation required for all fields by default (default: false)
--instanceName value This parameter can be used to name different swagger document instances. It is optional.
--overridesFile value File to read global type overrides from. (default: " .swaggo " )
--parseGoList Parse dependency via ' go list ' (default: true)
--tags value, -t value A comma-separated list of tags to filter the APIs for which the documentation is generated.Special case if the tag is prefixed with the ' ! ' character then the APIs with that tag will be excluded
--templateDelims value, --td value Provide custom delimiters for Go template generation. The format is leftDelim,rightDelim. For example: " [[,]] "
--collectionFormat value, --cf value Set default collection format (default: " csv " )
--state value Initial state for the state machine (default: " " ), @HostState in root file, @State in other files
--parseFuncBody Parse API info within body of functions in go files, disabled by default (default: false)
--help, -h show help (default: false)swag fmt -h
NAME:
swag fmt - format swag comments
USAGE:
swag fmt [command options] [arguments...]
OPTIONS:
--dir value, -d value Directories you want to parse,comma separated and general-info file must be in the first one (default: " ./ " )
--exclude value Exclude directories and files when searching, comma separated
--generalInfo value, -g value Go file path in which ' swagger general API Info ' is written (default: " main.go " )
--help, -h show help (default: false)
Encontre o código -fonte do exemplo aqui.
Termine as etapas para começar
swag init para gerar documentos Swagger 2.0, importe os seguintes pacotes: import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed filesmain.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 [email protected]
// @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 gerais da API podem ser definidas dinamicamente. O pacote de código gerado docs a variável SwaggerInfo que podemos usar para definir o caminho do título, descrição, versão, host e base de base programaticamente. Exemplo usando 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 [email protected]
// @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 ()
}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 initOs comentários dos ganhos podem ser formatados automaticamente, assim como 'GO FMT'. Encontre o resultado da formatação aqui.
Uso:
swag fmtExcluir pasta:
swag fmt -d ./ --exclude ./internal Ao usar swag fmt , você precisa garantir que você tenha um comentário do documento para a função para garantir a formatação correta. Isso se deve ao swag fmt Recunting Swag Comentários com guias, o que só é permitido após um comentário padrão do documento.
Por exemplo, use
// 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 ) {Documento Swagger 2.0
Exemplo Celler/Main.go
| anotação | descrição | exemplo |
|---|---|---|
| título | Obrigatório. O título do aplicativo. | // @title swagger exemplo API |
| versão | Obrigatório. Fornece a versão da API do aplicativo. | // @version 1.0 |
| descrição | Uma breve descrição do aplicativo. | // @Description Este é um servidor de servidor de amostra. |
| tag.name | Nome de uma tag. | // @tag.name este é o nome da tag |
| tag.Description | Descrição da tag | // @tag.description Descrição legal |
| tag.docs.url | URL da documentação externa da tag | // @tag.docs.url https://example.com |
| tag.docs.description | Descrição da documentação externa da tag | // @tag.docs.description Melhor exemplo documentação |
| Termos de Serviço | Os termos de serviço para a API. | // @termsofservice http://swagger.io/terms/ |
| contact.name | As informações de contato para a API exposta. | // @contact.name API Support |
| contact.url | O URL apontando para as informações de contato. Deve estar no formato de um URL. | // @contact.url http://www.swagger.io/support |
| contact.Email | O endereço de e -mail da pessoa/organização de contato. Deve estar no formato de um endereço de e -mail. | // @contact.email [email protected] |
| License.name | Obrigatório. O nome da licença usado para a API. | // @Licença.name Apache 2.0 |
| licença.url | Um URL para a licença usada para a API. Deve estar no formato de um URL. | // @Licença.url http://www.apache.org/license/license-2.0.html |
| hospedar | O host (nome ou IP) que serve a API. | // @host localhost: 8080 |
| Basepath | O caminho base no qual a API é servida. | // @Basepath/API/V1 |
| aceitar | Uma lista de tipos de MIME que as APIs podem consumir. Observe que a aceitação afeta apenas as operações com um órgão de solicitação, como postagem, put e patch. O valor deve ser conforme descrito em tipos de MIME. | // @ACcept JSON |
| produzir | Uma lista de tipos de MIME que as APIs podem produzir. O valor deve ser conforme descrito em tipos de MIME. | // @produce json |
| query.collection.format | O formato de param de coleção padrão (Array) na consulta, enums: CSV, Multi, Pipes, TSV, SSV. Se não estiver definido, o CSV é o padrão. | // @query.collection.format multi |
| esquemas | O protocolo de transferência para a operação que se separou por espaços. | // @schemes http https |
| externalDocs.Description | Descrição do documento externo. | // @externalDocs.Description OpenApi |
| externalDocs.url | URL do documento externo. | // @externaldocs.url https://swagger.io/resources/open-api/ |
| x-name | A chave de extensão deve ser iniciada por x- e assumir apenas o valor JSON | // @x-expler-key {"key": "value"} |
Quando uma string curta em sua documentação é insuficiente ou você precisa de imagens, exemplos de código e coisas assim, você pode usar descrições de marcação. Para usar as descrições de marcação, use as seguintes anotações.
| anotação | descrição | exemplo |
|---|---|---|
| título | Obrigatório. O título do aplicativo. | // @title swagger exemplo API |
| versão | Obrigatório. Fornece a versão da API do aplicativo. | // @version 1.0 |
| Descrição.Markdown | Uma breve descrição do aplicativo. Analisado no arquivo api.md. Esta é uma alternativa ao @Description | // @description.markdown Não é necessário valor, isso analisa a descrição da api.md |
| tag.name | Nome de uma tag. | // @tag.name este é o nome da tag |
| tag.description.markdown | Descrição da tag Esta é uma alternativa para tag.Description. A descrição será lida em um arquivo chamado como tagname.md | // @tag.description.markdown |
| tag.x-name | A chave de extensão deve ser iniciada por x- e assumir apenas o valor da string | // @x-example-key Valor |
Exemplo Celler/Controller
| anotação | descrição |
|---|---|
| descrição | Uma explicação detalhada do comportamento da operação. |
| Descrição.Markdown | Uma breve descrição do aplicativo. A descrição será lida em um arquivo. Por exemplo, @description.markdown details details.md |
| eu ia | Uma string exclusiva usada para identificar a operação. Deve ser único entre todas as operações da API. |
| tags | Uma lista de tags para cada operação da API que separou por vírgulas. |
| resumo | Um breve resumo do que a operação faz. |
| aceitar | Uma lista de tipos de MIME que as APIs podem consumir. Observe que a aceitação afeta apenas as operações com um órgão de solicitação, como postagem, put e patch. O valor deve ser conforme descrito em tipos de MIME. |
| produzir | Uma lista de tipos de MIME que as APIs podem produzir. O valor deve ser conforme descrito em tipos de MIME. |
| param | Parâmetros que separaram por espaços. param name , param type , data type , is mandatory? , Atributo comment attribute(optional) |
| segurança | Segurança para cada operação da API. |
| sucesso | Resposta de sucesso que separou por espaços. return code or default , {param type} , data type , comment |
| falha | Resposta de falha que separou por espaços. return code or default , {param type} , data type , comment |
| resposta | Da mesma forma que success e failure |
| cabeçalho | Cabeçalho em resposta que separou por espaços. return code , {param type} , data type , comment |
| roteador | Definição de caminho que separou por espaços. path , [httpMethod] |
| Router depreciado | Da mesma forma que o roteador, mas depreciado. |
| x-name | A chave de extensão deve ser iniciada por X- e assumir apenas o valor JSON. |
| x-codesample | Uso opcional de marcação. Pegue file como parâmetro. Isso procurará um arquivo nomeado como o resumo na pasta fornecida. |
| descontinuado | Mark endpoint como depreciado. |
swag aceita todos os tipos de MIME que estão no formato correto, ou seja, corresponder */* . Além disso, swag também aceita aliases para alguns tipos de mímica da seguinte forma:
| Alias | MIME TIPO |
|---|---|
| JSON | Aplicação/JSON |
| xml | texto/xml |
| simples | texto/simples |
| html | texto/html |
| mpfd | Multipart/Form-Data |
| X-WWW-Form-Form-Urlencoded | APLICAÇÃO/X-WWW-FORM-URLENCODED |
| JSON-API | APLICAÇÃO/VND.API+JSON |
| json-stream | APLICAÇÃO/X-JSON-stream |
| stream de octeto | aplicação/stream de octeto |
| png | imagem/png |
| JPEG | imagem/jpeg |
| gif | imagem/gif |
| anotação | descrição | parâmetros | exemplo |
|---|---|---|---|
| SecurityDefinitions.basic | Auth Basic. | // @SecurityDefinitions.Basic BasicAuth | |
| SecurityDefinitions.apikey | API KEY AUTH. | em, nome, descrição | // @SecurityDefinitions.apikey apikeyauth |
| SecurityDefinitions.oauth2.Application | OAuth2 Aplicativo Auth. | Tokenurl, escopo, descrição | // @SecurityDefinitions.oauth2.Application oAuth2Application |
| SecurityDefinitions.oauth2.implicic | OAuth2 Auth. | Autorização, escopo, descrição | // @SecurityDefinitions.oauth2.implictic outh2implicic |
| SecurityDefinitions.oauth2.password | OAuth2 senha auth. | Tokenurl, escopo, descrição | // @SecurityDefinitions.oauth2.password oauth2password |
| SecurityDefinitions.oauth2.AccessCode | OAuth2 Código de acesso Auth. | tokenurl, autorização, escopo, descrição | // @SecurityDefinitions.oauth2.AccessCode OAuth2AccessCode |
| Anotação de parâmetros | exemplo |
|---|---|
| em | // @in cabeçalho |
| nome | // Autorização @Name |
| Tokenurl | // @tokenurl https://example.com/oauth/token |
| Autorizationurl | // @authorizationurl https://example.com/oauth/authorize |
| escopo.hoge | // @Scope.Write Subsídios Escreva acesso |
| descrição | // @Description OAuth protege nossos terminais de entidade |
// @Param enumstring query string false "string enums" Enums(A, B, C)
// @Param enumint query int false "int enums" Enums(1, 2, 3)
// @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3)
// @Param string query string false "string valid" minlength(5) maxlength(10)
// @Param int query int false "int valid" minimum(1) maximum(10)
// @Param default query string false "string default" default(A)
// @Param example query string false "string example" example(string)
// @Param collection query []string false "string collection" collectionFormat(multi)
// @Param extensions query []string false "string collection" extensions(x-example=test,x-nullable)Ele também funciona para os campos da estrutura:
type Foo struct {
Bar string `minLength:"4" maxLength:"16" example:"random string"`
Baz int `minimum:"10" maximum:"20" default:"15"`
Qux [] string `enums:"foo,bar,baz"`
}| Nome do campo | Tipo | Descrição |
|---|---|---|
| validar | string | Determina a validação para o parâmetro. Os valores possíveis são: required,optional . |
| padrão | * | Declara o valor do parâmetro que o servidor usará se não for fornecido, por exemplo, uma "contagem" para controlar o número de resultados por página poderá fazer o padrão de 100 se não for fornecido pelo cliente na solicitação. (Nota: "padrão" não tem significado para os parâmetros necessários.) Consulte https://tools.ietf.org/html/draft-fge-json-schema-validation-00#secção-6.2. Ao contrário do esquema JSON, esse valor deve estar em conformidade com o type definido para este parâmetro. |
| máximo | number | Consulte https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. |
| mínimo | number | Veja https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. |
| múltiplo de | number | Veja https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. |
| maxlength | integer | Veja https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1. |
| MinLength | integer | Veja https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2. |
| enums | [*] | Veja https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1. |
| formatar | string | O formato estendendo para o type mencionado anteriormente. Consulte os formatos de tipo de dados para obter mais detalhes. |
| Coleção FORMAT | string | Determina o formato da matriz se a matriz do tipo for usada. Valores possíveis são:
csv . |
| exemplo | * | Declara o exemplo para o valor do parâmetro |
| extensões | string | Adicione a extensão aos parâmetros. |
| Nome do campo | Tipo | Descrição |
|---|---|---|
| padrão | string | Veja https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. |
| Maxitems | integer | Veja https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. |
| minitems | integer | Veja https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. |
| ÚNICOITEMS | boolean | Veja https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. |
Você pode adicionar descrições que abrangem várias linhas na descrição geral da API ou nas definições de rotas como assim:
// @description This is the first line
// @description This is the second line
// @description And so forth. // @Success 200 {array} model.Account <-- This is a user defined struct. package model
type Account struct {
ID int `json:"id" example:"1"`
Name string `json:"name" example:"account name"`
} Você pode declarar estruturas de resposta de sua solicitação dentro de um corpo de função. Você deve seguir a convenção de nomenclatura <package-name>.<function-name>.<struct-name>
package main
// @Param request body main.MyHandler.request true "query params"
// @Success 200 {object} main.MyHandler.response
// @Router /test [post]
func MyHandler () {
type request struct {
RequestField string
}
type response struct {
ResponseField string
}
} // JSONResult's data field will be overridden by the specific type proto.Order
@ success 200 { object } jsonresult. JSONResult { data = proto . Order } "desc" type JSONResult struct {
Code int `json:"code" `
Message string `json:"message"`
Data interface {} `json:"data"`
}
type Order struct { //in `proto` package
Id uint `json:"id"`
Data interface {} `json:"data"`
}@ success 200 { object } jsonresult. JSONResult { data = []proto. Order } "desc"
@ success 200 { object } jsonresult. JSONResult { data = string } "desc"
@ success 200 { object } jsonresult. JSONResult { data = [] string } "desc"@ success 200 { object } jsonresult. JSONResult { data1 = string , data2 = [] string , data3 = proto . Order , data4 = []proto. Order } "desc" type DeepObject struct { //in `proto` package
...
}
@ success 200 { object } jsonresult. JSONResult { data1 = proto. Order { data = proto . DeepObject }, data2 = []proto. Order { data = []proto. DeepObject }} "desc" // @Param X-MyHeader header string true "MyHeader must be set for valid response"
// @Param X-API-VERSION header string true "API version eg.: 1.0" // @Success 200 {string} string "ok"
// @failure 400 {string} string "error"
// @response default {string} string "other error"
// @Header 200 {string} Location "/entity/1"
// @Header 200,400,default {string} Token "token"
// @Header all {string} Token2 "token2" /// ...
// @Param group_id path int true "Group ID"
// @Param account_id path int true "Account ID"
// ...
// @Router /examples/groups/{group_id}/accounts/{account_id} [get] /// ...
// @Param group_id path int true "Group ID"
// @Param user_id path int true "User ID"
// ...
// @Router /examples/groups/{group_id}/user/{user_id}/address [put]
// @Router /examples/user/{user_id}/address [put] type Account struct {
ID int `json:"id" example:"1"`
Name string `json:"name" example:"account name"`
PhotoUrls [] string `json:"photo_urls" example:"http://test/image/1.jpg,http://test/image/2.jpg"`
} // @Param email body string true "message/rfc822" SchemaExample(Subject: TestmailrnrnBody Messagern) // Account model info
// @Description User account information
// @Description with user id and username
type Account struct {
// ID this is userid
ID int `json:"id"`
Name string `json:"name"` // This is Name
} #708 O analisador lida apenas com os comentários de estruturas começando com o atributo @Description . Mas ele escreve todos os comentários de campo da estrutura como estão.
Então, gerou Doc da Swagger da seguinte forma:
"Account" : {
"type" : " object " ,
"description" : " User account information with user id and username "
"properties" : {
"id" : {
"type" : " integer " ,
"description" : " ID this is userid "
},
"name" : {
"type" : " string " ,
"description" : " This is Name "
}
}
}#201
type TimestampTime struct {
time. Time
}
///implement encoding.JSON.Marshaler interface
func ( t * TimestampTime ) MarshalJSON () ([] byte , error ) {
bin := make ([] byte , 16 )
bin = strconv . AppendInt ( bin [: 0 ], t . Time . Unix (), 10 )
return bin , nil
}
func ( t * TimestampTime ) UnmarshalJSON ( bin [] byte ) error {
v , err := strconv . ParseInt ( string ( bin ), 10 , 64 )
if err != nil {
return err
}
t . Time = time . Unix ( v , 0 )
return nil
}
///
type Account struct {
// Override primitive type by simply specifying it via `swaggertype` tag
ID sql. NullInt64 `json:"id" swaggertype:"integer"`
// Override struct type to a primitive type 'integer' by specifying it via `swaggertype` tag
RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`
// Array types can be overridden using "array,<prim_type>" format
Coeffs []big. Float `json:"coeffs" swaggertype:"array,number"`
}#379
type CerticateKeyPair struct {
Crt [] byte `json:"crt" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
Key [] byte `json:"key" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
}Gerou Swagger Doc da seguinte forma:
"api.MyBinding" : {
"type" :" object ",
"properties" :{
"crt" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
},
"key" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
}
}
} Se você estiver usando arquivos gerados, as tags swaggertype ou swaggerignore podem não ser possíveis.
Ao passar um mapeamento para SWAG com --overridesFile você pode dizer a Swag para usar um tipo no lugar de outro onde quer que ele apareça. Por padrão, se um arquivo .swaggo estiver presente no diretório atual, ele será usado.
Vá código:
type MyStruct struct {
ID sql. NullInt64 `json:"id"`
Name sql. NullString `json:"name"`
} .swaggo :
// Replace all NullInt64 with int
replace database/sql.NullInt64 int
// Don't include any fields of type database/sql.NullString in the swagger docs
skip database/sql.NullString
Diretivas possíveis são comentários (começando com // ), replace path/to/a.type path/to/b.type e skip path/to/a.type .
(Observe que os caminhos completos para todos os tipos nomeados devem ser fornecidos para evitar problemas quando vários pacotes definem um tipo com o mesmo nome)
Renderizado:
"types.MyStruct" : {
"id" : "integer"
} type Account struct {
ID string `json:"id"`
Name string `json:"name"`
Ignored int `swaggerignore:"true"`
} type Account struct {
ID string `json:"id" extensions:"x-nullable,x-abc=def,!x-omitempty"` // extensions fields must start with "x-"
}Gere Doc Swagger como segue:
"Account" : {
"type" : "object" ,
"properties" : {
"id" : {
"type" : "string" ,
"x-nullable" : true ,
"x-abc" : "def" ,
"x-omitempty" : false
}
}
} type Resp struct {
Code int
} //@name ResponseInformações gerais da API.
// @securityDefinitions.basic BasicAuth
// @securitydefinitions.oauth2.application OAuth2Application
// @tokenUrl https://example.com/oauth/token
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative informationCada operação da API.
// @Security ApiKeyAuthFaça ou condição
// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]Faça e condicionar
// @Security ApiKeyAuth && firebase
// @Security OAuth2Application[write, admin] && APIKeyAuth type Example struct {
// Sort order:
// * asc - Ascending, from A to Z.
// * desc - Descending, from Z to A.
Order string `enums:"asc,desc"`
} Por padrão, o comando swag gera especificação de swagger em três tipos diferentes de arquivos/arquivos:
Se você deseja limitar um conjunto de tipos de arquivo que devem ser gerados, você pode usar o sinalizador --outputTypes (curto -ot ). O valor padrão é go,json,yaml - Tipos de saída separados com vírgula. Para limitar a saída apenas para go e os arquivos yaml , você escreveria go,yaml . Com o comando completo que seria swag init --outputTypes go,yaml .
// @Success 200 {object} web.GenericNestedResponse[types.Post]
// @Success 204 {object} web.GenericNestedResponse[types.Post, Types.AnotherOne]
// @Success 201 {object} web.GenericNestedResponse[web.GenericInnerType[types.Post]]
func GetPosts ( w http. ResponseWriter , r * http. Request ) {
_ = web. GenericNestedResponse [types. Post ]{}
}Veja este arquivo para obter mais detalhes e outros exemplos.
#980 #1177
Se as suas anotações de swagger ou campos de estrutura contiverem "{{" ou "}}", a geração de modelos provavelmente falhará, pois esses são os delimitadores padrão para os modelos GO.
Para fazer a geração funcionar corretamente, você pode alterar os delimitadores padrão com -td . Por exemplo:
swag init -g http/api.go -td "[[,]]" O novo delimitador é uma string com o formato " <left delimiter> , <right delimiter> ".
Se a estrutura for definida em um pacote de dependência, use --parseDependency .
Se a estrutura for definida em seu projeto principal, use --parseInternal .
Se você deseja incluir dependências internas e de dependências, use ambos os sinalizadores
swag init --parseDependency --parseInternal
Este projeto foi inspirado em Yvasiyarov/Swagger, mas simplificamos o uso e adicionamos uma variedade de estruturas da web. Gopher Image Source é Tenntenn/Gopher-Stickers. Possui licenças de licenciamento criativo do Commons.
Este projeto existe graças a todas as pessoas que contribuem. [Contribuir].
Obrigado a todos os nossos apoiadores! [Torne -se um patrocinador]
Apoie este projeto, tornando -se um patrocinador. Seu logotipo aparecerá aqui com um link para o seu site. [Torne -se um patrocinador]
