swag
v1.16.4
? Inglés ∙ 简体中文 ∙ Português
Swag Convierts Go Annotations a Swagger Documentation 2.0. Hemos creado una variedad de complementos para marcos web populares GO. Esto le permite integrarse rápidamente con un proyecto GO existente (usando la interfaz de usuario de Swagger).
Agregue comentarios a su código fuente de API, consulte el formato de comentarios declarativos.
Instale Swag usando:
go install github.com/swaggo/swag/cmd/swag@latestPara construir desde la fuente necesita ir (1.19 o más nuevo).
Alternativamente, puede ejecutar la imagen Docker:
docker run --rm -v $( pwd ) :/code ghcr.io/swaggo/swag:latestO descargue un binario precompilado desde la página de lanzamiento.
swag init en la carpeta raíz del proyecto que contiene el archivo main.go Esto analizará sus comentarios y generará los archivos requeridos (Carpeta docs y docs/docs.go . swag init Asegúrese de importar los docs/docs.go generados. GO para que su configuración específica se init . Si sus anotaciones API generales no viven en main.go , puede dejar que Swag lo sepa con la bandera -g .
import _ "example-module-name/docs" swag init -g http/api.goswag fmt el comentario de Swag. (Actualice a la última versión) 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)
Encuentre el código fuente de ejemplo aquí.
Termina los pasos para comenzar
swag init para generar documentos Swagger 2.0, importe los siguientes paquetes: 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" )
}
//... Además, alguna información general de API se puede establecer dinámicamente. El paquete de código generado docs exporta la variable SwaggerInfo que podemos usar para establecer el título, la descripción, la versión, el host y la ruta base mediante programación. Ejemplo 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 initLos comentarios de Swag se pueden formatear automáticamente, al igual que 'Go FMT'. Encuentre el resultado de formatear aquí.
Uso:
swag fmtExcluir carpeta:
swag fmt -d ./ --exclude ./internal Al usar swag fmt , debe asegurarse de tener un comentario de DOC para la función para garantizar el formateo correcto. Esto se debe a los comentarios swag fmt de Swag con pestañas, que solo se permiten después de un comentario estándar de DOC.
Por ejemplo, usa
// 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
Ejemplo de celular/main.go
| anotación | descripción | ejemplo |
|---|---|---|
| título | Requerido. El título de la aplicación. | // @Title Swagger Ejemplo API |
| versión | Requerido. Proporciona la versión de la API de la aplicación. | // @version 1.0 |
| descripción | Una breve descripción de la aplicación. | // @Description Este es un servidor de celular del servidor de muestras. |
| etiqueta.name | Nombre de una etiqueta. | // @tag.name Este es el nombre de la etiqueta |
| etiqueta. Descripción | Descripción de la etiqueta | // @Tag.Description Descripción genial |
| tag.docs.url | URL de la documentación externa de la etiqueta | // @tag.docs.url https://example.com |
| Tag.docs.Description | Descripción de la documentación externa de la etiqueta | // @tag.docs.description El mejor ejemplo de documentación |
| Términos de servicio | Los términos de servicio para la API. | // @termsofservice http://swagger.io/terms/ |
| Contacto. Nombre | La información de contacto para la API expuesta. | // @contact.name Soporte de la API |
| contacto.url | La URL apunta a la información de contacto. Debe estar en el formato de una URL. | // @contact.url http://www.swagger.io/support |
| Contacto. | La dirección de correo electrónico de la persona/organización de contacto. Debe estar en el formato de una dirección de correo electrónico. | // @contact.email [email protected] |
| Licencia. Nombre | Requerido. El nombre de la licencia utilizado para la API. | // @License.Name Apache 2.0 |
| licencia.url | Una URL de la licencia utilizada para la API. Debe estar en el formato de una URL. | // @licencia.url http://www.apache.org/licenses/license-2.0.html |
| anfitrión | El host (nombre o IP) que sirve a la API. | // @host localhost: 8080 |
| Basepath | El camino base en el que se sirve la API. | // @BASEPATH/API/V1 |
| aceptar | Una lista de tipos de MIME Las API pueden consumir. Tenga en cuenta que aceptar solo afecta las operaciones con un cuerpo de solicitud, como Post, Put y Patch. El valor debe ser como se describe en los tipos MIME. | // @accept json |
| producir | Una lista de tipos de MIME que las API pueden producir. El valor debe ser como se describe en los tipos MIME. | // @produce json |
| Query.Collection.Format | El formato de parámetro de colección predeterminada (matriz) en consulta, enums: CSV, multi, tuberías, TSV, SSV. Si no se establece, CSV es el valor predeterminado. | // @query.collection.format multi |
| esquemas | El protocolo de transferencia para la operación que se separó por espacios. | // @schemes http https |
| externo -descripción | Descripción del documento externo. | // @externoChocs.description Openapi |
| externaldocs.url | URL del documento externo. | // @externosaldocs.url https://swagger.io/resources/open-api/ |
| X nombre | La clave de extensión debe ser iniciada por X- y tomar solo el valor JSON | // @x-exame-key {"clave": "valor"} |
Cuando una cadena corta en su documentación es insuficiente, o necesita imágenes, ejemplos de código y cosas así, es posible que desee usar descripciones de Markdown. Para usar descripciones de Markdown, use las siguientes anotaciones.
| anotación | descripción | ejemplo |
|---|---|---|
| título | Requerido. El título de la aplicación. | // @Title Swagger Ejemplo API |
| versión | Requerido. Proporciona la versión de la API de la aplicación. | // @version 1.0 |
| Descripción.markdown | Una breve descripción de la aplicación. Analizado desde el archivo API.MD. Esta es una alternativa a @description | // @Descripción.markdown No se necesita valor, esto analiza la descripción de API.MD |
| etiqueta.name | Nombre de una etiqueta. | // @tag.name Este es el nombre de la etiqueta |
| tag.description.markdown | Descripción de la etiqueta Esta es una alternativa a Tag.Description. La descripción se leerá de un archivo llamado como TagName.md | // @tag.description.markdown |
| Tag.x-nombre | La clave de extensión, debe ser iniciada por X- y tomar solo el valor de cadena | // @x-exame-key value |
Ejemplo de celular/controlador
| anotación | descripción |
|---|---|
| descripción | Una explicación detallada del comportamiento de operación. |
| Descripción.markdown | Una breve descripción de la aplicación. La descripción se leerá de un archivo. Por ejemplo @description.markdown details cargarán details.md |
| identificación | Una cadena única utilizada para identificar la operación. Debe ser único entre todas las operaciones de API. |
| etiquetas | Una lista de etiquetas a cada operación de API que se separa por comas. |
| resumen | Un breve resumen de lo que hace la operación. |
| aceptar | Una lista de tipos de MIME Las API pueden consumir. Tenga en cuenta que aceptar solo afecta las operaciones con un cuerpo de solicitud, como Post, Put y Patch. El valor debe ser como se describe en los tipos MIME. |
| producir | Una lista de tipos de MIME que las API pueden producir. El valor debe ser como se describe en los tipos MIME. |
| parámetro | Parámetros que se separan por espacios. param name , param type , data type , is mandatory? , atributo comment attribute(optional) |
| seguridad | Seguridad a cada operación de API. |
| éxito | Respuesta de éxito que se separó por espacios. return code or default , {param type} , data type , comment |
| falla | Respuesta de falla que se separó por espacios. return code or default , {param type} , data type , comment |
| respuesta | Al igual que success y failure |
| encabezamiento | Encabezado en respuesta que se separa por espacios. return code , {param type} , data type , comment |
| enrutador | Definición de ruta que se separó por espacios. path , [httpMethod] |
| desordenado | Al igual que el enrutador, pero en desuso. |
| X nombre | La clave de extensión debe ser iniciada por X- y tomar solo el valor JSON. |
| X-Codesample | Uso opcional de Markdown. Tome file como parámetro. Esto buscará un archivo llamado como el resumen en la carpeta dada. |
| desapercibido | Marque el punto final como desapercibido. |
swag acepta todos los tipos de MIME que están en el formato correcto, es decir, coincidir */* . Además de eso, swag también acepta alias para algunos tipos de MIME de la siguiente manera:
| Alias | Tipo mimo |
|---|---|
| json | Aplicación/JSON |
| xml | texto/XML |
| plano | texto/simple |
| html | texto/html |
| mpfd | Data multipart/formulario |
| x-www-form-urlencoded | aplicación/x-www-form-urlencoded |
| json-api | Aplicación/VND.API+JSON |
| rayado de json | Aplicación/X-Json-stream |
| transmisión de octeto | Aplicación/transmisión de octeto |
| png | Imagen/PNG |
| jpeg | Imagen/jpeg |
| gif | Imagen/GIF |
| anotación | descripción | parámetros | ejemplo |
|---|---|---|---|
| SecurityDefinitions.Basic | Auth. | // @SecurityDefinitions.Basic Basicauth | |
| SecurityDefinitions.apikey | API KEY AUTH. | en, nombre, descripción | // @SecurityDefinitions.apikey ApikeyAuth |
| SecurityDefinitions.oauth2.Application | OAUTH2 Aplicación Auth. | tokenurl, alcance, descripción | // @SecurityDefinitions.oauth2.Application Oauth2Application |
| SecurityDefinitions.oauth2.impplicit | OAUTH2 Auth. | AutorizationUrl, alcance, descripción | // @SecurityDefinitions.oauth2.implicit oauth2ImpliCit |
| SecurityDefinitions.oauth2.Password | OAuth2 Password Auth. | tokenurl, alcance, descripción | // @SecurityDefinitions.oauth2.Password OAuth2Password |
| SecurityDefinitions.oauth2.accesscode | OAUTH2 Código de acceso Auth. | tokenurl, autorización, alcance, descripción | // @SecurityDefinitions.oauth2.AccessCode Oauth2AccessCode |
| anotación de parámetros | ejemplo |
|---|---|
| en | // @in encabezado |
| nombre | // Autorización @@name |
| tokenurl | // @tokenurl https://example.com/oauth/token |
| autorización | // @authorizationUrl https://example.com/oauth/authorize |
| alcance.hoge | // @scope.write subvenciones de escritura |
| descripción | // @description oauth protege nuestros puntos finales de entidad |
// @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)También funciona para los campos de estructura:
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"`
}| Nombre de campo | Tipo | Descripción |
|---|---|---|
| validar | string | Determina la validación para el parámetro. Los valores posibles son: required,optional . |
| por defecto | * | Declara el valor del parámetro que el servidor usará si no se proporciona ninguno, por ejemplo, un "recuento" para controlar el número de resultados por página podría predeterminar a 100 si no suministra el cliente en la solicitud. (Nota: "predeterminado" no tiene significado para los parámetros requeridos.) Consulte https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. A diferencia del esquema JSON, este valor debe cumplir con el type definido para este parámetro. |
| máximo | number | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. |
| mínimo | number | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. |
| múltiple | number | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. |
| longitud máxima | integer | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1. |
| mínimo | integer | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2. |
| enumeros | [*] | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1. |
| formato | string | El formato de extensión para el type mencionado anteriormente. Consulte los formatos de tipo de datos para obtener más detalles. |
| colección format | string | Determina el formato de la matriz si se usa la matriz de tipo. Los valores posibles son:
csv . |
| ejemplo | * | Declara el ejemplo del valor del parámetro |
| extensiones | string | Agregue la extensión a los parámetros. |
| Nombre de campo | Tipo | Descripción |
|---|---|---|
| patrón | string | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. |
| maxitems | integer | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. |
| minitema | integer | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. |
| Uniqueitems | boolean | Ver https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. |
Puede agregar descripciones que abarcan múltiples líneas en la descripción general de la API o las definiciones de rutas como así:
// @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"`
} Puede declarar las estructuras de respuesta de su solicitud dentro de un cuerpo de funciones. Debe tener que seguir la convención de nombres <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 El analizador maneja solo los comentarios de estructura que comienzan con el atributo @Description . Pero escribe todos los comentarios de Struct Field tal como está.
Entonces, el Doc de Swagger generado de la siguiente manera:
"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=="`
}Swagger Doc generado de la siguiente manera:
"api.MyBinding" : {
"type" :" object ",
"properties" :{
"crt" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
},
"key" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
}
}
} Si está utilizando archivos generados, las etiquetas swaggertype o swaggerignore pueden no ser posibles.
Al pasar un mapeo para swag con --overridesFile puede decirle a Swag que use un tipo en lugar de otro donde aparezca. Por defecto, si un archivo .swaggo está presente en el directorio actual, se utilizará.
Código Go:
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
Las posibles directivas son comentarios (que comienzan con // ), replace path/to/a.type path/to/b.type skip path/to/a.type a.
(Tenga en cuenta que se deben proporcionar las rutas completas a cualquier tipo nombrado para evitar problemas cuando múltiples paquetes definen un tipo con el mismo nombre)
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-"
}Genere Swagger Doc de la siguiente manera:
"Account" : {
"type" : "object" ,
"properties" : {
"id" : {
"type" : "string" ,
"x-nullable" : true ,
"x-abc" : "def" ,
"x-omitempty" : false
}
}
} type Resp struct {
Code int
} //@name ResponseInformación general de la 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 operación de API.
// @Security ApiKeyAuthHazlo o condición
// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]Hazlo y condición
// @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 defecto, el comando swag genera especificación de swagger en tres archivos/tipos de archivos diferentes:
Si desea limitar un conjunto de tipos de archivos que deben generarse, puede usar el indicador --outputTypes (Short -ot ). El valor predeterminado es los tipos de salida go,json,yaml : separados con coma. Para limitar la salida solo para go y los archivos yaml , escribiría go,yaml . Con comando completo que sería 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 ]{}
}Vea este archivo para obtener más detalles y otros ejemplos.
#980 #1177
Si sus anotaciones swagger o campos de estructura contienen "{{" o "}}", la generación de plantillas probablemente fallará, ya que estos son los delimitadores predeterminados para las plantillas GO.
Para que la generación funcione correctamente, puede cambiar los delimitadores predeterminados con -td . Por ejemplo:
swag init -g http/api.go -td "[[,]]" El nuevo delimitador es una cadena con el formato " <left delimiter> , <right delimiter> ".
Si la estructura se define en un paquete de dependencia, use --parseDependency .
Si la estructura se define en su proyecto principal, use --parseInternal .
Si desea incluir tanto interno como de dependencias, use ambas banderas
swag init --parseDependency --parseInternal
Este proyecto se inspiró en Yvasiyarov/Swagger, pero simplificamos el uso y agregamos soporte una variedad de marcos web. La fuente de imagen de Gopher es Tenntenn/Gopher-sickers. Tiene licencias de licencia Creative Commons.
Este proyecto existe gracias a todas las personas que contribuyen. [Contribuir].
¡Gracias a todos nuestros patrocinadores! [Conviértete en un patrocinador]
Apoye este proyecto al convertirse en patrocinador. Su logotipo aparecerá aquí con un enlace a su sitio web. [Convertirse en patrocinador]
