swag
v1.16.4
? Anglais ∙ 简体中文 ∙ Português
Les convertis SWAG font des annotations en documentation Swagger 2.0. Nous avons créé une variété de plugins pour les frameworks Web GO populaires. Cela vous permet de vous intégrer rapidement à un projet GO existant (en utilisant Swagger UI).
Ajoutez des commentaires à votre code source API, voir le format de commentaires déclaratifs.
Installez Swag en utilisant:
go install github.com/swaggo/swag/cmd/swag@latestPour construire à partir de la source, vous avez besoin de GO (1.19 ou plus récent).
Vous pouvez également exécuter l'image Docker:
docker run --rm -v $( pwd ) :/code ghcr.io/swaggo/swag:latestOu téléchargez un binaire pré-compilé à partir de la page de version.
swag init dans le dossier racine du projet qui contient le fichier main.go Cela analysera vos commentaires et générera les fichiers requis (dossier docs et docs/docs.go ). swag init Assurez-vous d'importer les docs/docs.go afin que votre configuration spécifique soit init 'ed. Si vos annotations API générales ne vivent pas dans main.go , vous pouvez le faire savoir avec Swag avec le drapeau -g .
import _ "example-module-name/docs" swag init -g http/api.goswag fmt Format le commentaire Swag. (Veuillez passer à la dernière version) 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)
Trouvez l'exemple de code source ici.
Terminez les étapes pour commencer
swag init pour générer des documents Swagger 2.0, importez les packages suivants: 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" )
}
//... De plus, certaines informations générales d'API peuvent être définies dynamiquement. Le package de code généré docs exporte la variable SwaggerInfo que nous pouvons utiliser pour définir le titre, la description, la version, l'hôte et le chemin de base par programme. Exemple utilisant le 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 initLes commentaires SWAG peuvent être automatiquement formatés, tout comme «Go FMT». Trouvez le résultat de la mise en forme ici.
Usage:
swag fmtExclure le dossier ：
swag fmt -d ./ --exclude ./internal Lorsque vous utilisez swag fmt , vous devez vous assurer que vous avez un commentaire DOC pour la fonction pour garantir le formatage correct. Cela est dû au swag fmt Indentation Swag Commentaires avec des onglets, qui n'est autorisé qu'après un commentaire DOC standard.
Par exemple, utiliser
// 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 ) {Document Swagger 2.0
Exemple Celer / Main.go
| annotation | description | exemple |
|---|---|---|
| titre | Requis. Le titre de l'application. | // @Title Swagger Exemple API |
| version | Requis. Fournit la version de l'API de l'application. | // @version 1.0 |
| description | Une brève description de l'application. | // @Description Il s'agit d'un exemple de serveur de serveur de serveurs. |
| tag.name | Nom d'une balise. | // @ tag.name C'est le nom de la balise |
| TAG.DESCRIPTION | Description de la balise | // @ tag.description cool Description |
| tag.docs.url | URL de la documentation externe de la balise | // @ tag.docs.url https://example.com |
| tag.docs.description | Description de la documentation externe de l'étiquette | // @ tag.docs.description Meilleur exemple de documentation |
| termes de service | Les conditions d'utilisation de l'API. | // @termsofservice http://swagger.io/terms/ |
| Nom de contact | Les coordonnées de l'API exposée. | // @ Contact.Name API Prise en charge |
| contact.url | L'URL pointant vers les coordonnées. Doit être dans le format d'une URL. | // @ contact.url http://www.swagger.io/support |
| contact.email | L'adresse e-mail de la personne de contact / organisation. Doit être sous le format d'une adresse e-mail. | // @ contact.email [email protected] |
| licence.name | Requis. Le nom de licence utilisé pour l'API. | // @ licence.name Apache 2.0 |
| licence.url | Une URL à la licence utilisée pour l'API. Doit être dans le format d'une URL. | // @ licence.url http://www.apache.org/licenses/license-2.0.html |
| hôte | L'hôte (nom ou IP) servant l'API. | // @host localhost: 8080 |
| Chemin de base | Le chemin de base sur lequel l'API est servie. | // @basepath / api / v1 |
| accepter | Une liste des types de mime que les API peuvent consommer. Notez que l'acceptation affecte uniquement les opérations avec un corps de demande, comme le poste, le put et le patch. La valeur doit être telle que décrite sous les types de mime. | // @accept json |
| produire | Une liste des types de mime que les API peuvent produire. La valeur doit être telle que décrite sous les types de mime. | // @produce json |
| query.collection.format | Le format de param de collection par défaut (array) dans Query, Enum: CSV, Multi, Pipes, TSV, SSV. Si ce n'est pas défini, CSV est la valeur par défaut. | // @ query.collection.format multiples |
| schémas | Le protocole de transfert pour l'opération séparés par les espaces. | // @schemes http https |
| externaldocs.desscription | Description du document externe. | // @ externaldocs.description openapi |
| externaldocs.url | URL du document externe. | // @ externaldocs.url https://swagger.io/resources/open-api/ |
| nom X | La clé d'extension doit être démarrée par X- et ne prendre que la valeur JSON | // @ X-Example-Key {"Key": "Value"} |
Lorsqu'une courte chaîne dans votre documentation est insuffisante ou que vous avez besoin d'images, d'exemples de code et de choses comme celle-là, vous voudrez peut-être utiliser des descriptions de Markdown. Afin d'utiliser les descriptions de Markdown, utilisez les annotations suivantes.
| annotation | description | exemple |
|---|---|---|
| titre | Requis. Le titre de l'application. | // @Title Swagger Exemple API |
| version | Requis. Fournit la version de l'API de l'application. | // @version 1.0 |
| Description.Markdown | Une brève description de l'application. Analysé à partir du fichier api.md. Ceci est une alternative à @Description | // @ description.markdown Aucune valeur nécessaire, cela analyse la description de API.md |
| tag.name | Nom d'une balise. | // @ tag.name C'est le nom de la balise |
| tag.description.markdown | Description de la balise Ceci est une alternative à TAG.Description. La description sera lue à partir d'un fichier nommé comme tagname.md | // @ tag.description.markdown |
| tag.x-name | La touche d'extension doit être démarrée par X- et ne prendre que la valeur de la chaîne | // @ Valeur X-Example-Key |
Exemple de Celler / contrôleur
| annotation | description |
|---|---|
| description | Une explication verbale du comportement de fonctionnement. |
| Description.Markdown | Une brève description de l'application. La description sera lue à partir d'un fichier. EG @description.markdown details Chargera details.md |
| identifiant | Une chaîne unique utilisée pour identifier l'opération. Doit être unique parmi toutes les opérations d'API. |
| balises | Une liste de balises à chaque opération API séparée par des virgules. |
| résumé | Un court résumé de ce que fait l'opération. |
| accepter | Une liste des types de mime que les API peuvent consommer. Notez que l'acceptation affecte uniquement les opérations avec un corps de demande, comme le poste, le put et le patch. La valeur doit être telle que décrite sous les types de mime. |
| produire | Une liste des types de mime que les API peuvent produire. La valeur doit être telle que décrite sous les types de mime. |
| paramot | Paramètres séparés par des espaces. param name , param type , data type , is mandatory? , Attribut comment attribute(optional) |
| sécurité | Sécurité à chaque opération API. |
| succès | Réponse du succès qui s'est séparée par les espaces. return code or default , {param type} , data type , comment |
| échec | Réponse de défaillance qui s'est séparée par les espaces. return code or default , {param type} , data type , comment |
| réponse | Comme le même success et failure |
| tête | En-tête en réponse séparée par les espaces. return code , {param type} , data type , comment |
| routeur | Définition du chemin séparée par les espaces. path , [httpMethod] |
| déprécié | Comme le même routeur, mais déprécié. |
| nom X | La clé d'extension doit être démarrée par X- et ne prendre que la valeur JSON. |
| code X | Utilisation en option de la marque. Prenez file en tant que paramètre. Cela recherchera ensuite un fichier nommé comme le résumé dans le dossier donné. |
| déprécié | Marquez le point de terminaison comme obsolète. |
swag accepte tous les types de mime qui sont dans le bon format, c'est-à-dire correspondre */* . En plus de cela, swag accepte également les alias pour certains types de mime comme suit:
| Alias | Type mime |
|---|---|
| json | Application / JSON |
| xml | texte / xml |
| plaine | texte / plaine |
| html | texte / html |
| MPFD | multipar / format de forme |
| x-www-forlencod | application / x-www-forme-urlencod |
| JSON-API | application / vnd.api + json |
| json | application / x-json-stream |
| circonscription en octet | application / trace d'octet |
| PNG | image / png |
| jpeg | image / jpeg |
| gif | image / gif |
| annotation | description | paramètres | exemple |
|---|---|---|---|
| securityDefinitions.basic | Auth. | // @ SecurityDefinitions.basic BasicAuth | |
| SecurityDefinitions.apikey | API Key Auth. | dans, nom, description | // @ SecurityDefinitions.apikey apikeyAuth |
| SecurityDefinitions.oAuth2.Application | OAuth2 Application Auth. | tokenurl, portée, description | // @ SecurityDefinitions.oAuth2.Application OAuth2Application |
| SecurityDefinitions.oAuth2.Implicit | OAuth2 Auth implicite. | AutorisationUrl, portée, description | // @ SecurityDefinitions.oAuth2.Implicit OAuth2Implicit |
| SecurityDefinitions.oAuth2.Password | Mot de passe OAuth2 Auth. | tokenurl, portée, description | // @ SecurityDefinitions.oAuth2.Password OAuth2Password |
| SecurityDefinitions.oAuth2.AccessCode | OAuth2 Access Code Auth. | tokenurl, autorisationurl, portée, description | // @ SecurityDefinitions.oAuth2.AccessCode OAuth2Accesscode |
| Annotation des paramètres | exemple |
|---|---|
| dans | // @in Header |
| nom | // @name Autorisation |
| tokenurl | // @tokenurl https://example.com/oauth/token |
| Autorisation | // @authorizationurl https://example.com/oauth/authorize |
| Scope.hoge | // @ scope.write subventions accès en écriture |
| description | // @Description OAuth protège nos points de terminaison entités |
// @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)Il fonctionne également pour les champs de structure:
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"`
}| Nom de champ | Taper | Description |
|---|---|---|
| valider | string | Détermine la validation du paramètre. Les valeurs possibles sont: required,optional . |
| défaut | * | Déclare la valeur du paramètre que le serveur utilisera si aucun n'est fourni, par exemple, un "compte" pour contrôler le nombre de résultats par page peut par défaut à 100 s'il n'est pas fourni par le client dans la demande. (Remarque: "Par défaut" n'a aucun sens pour les paramètres requis.) Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Contrairement au schéma JSON, cette valeur doit être conforme au type défini pour ce paramètre. |
| maximum | number | Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. |
| minimum | number | Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. |
| multiple | number | Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. |
| maxlange | integer | Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1. |
| minlengle | integer | Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2. |
| énumération | [*] | Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1. |
| format | string | Le format d'extension pour le type mentionné précédemment. Voir les formats de type de données pour plus de détails. |
| CollectionFormat | string | Détermine le format du tableau si le tableau de type est utilisé. Les valeurs possibles sont:
csv . |
| exemple | * | Déclare l'exemple de la valeur du paramètre |
| extensions | string | Ajoutez une extension aux paramètres. |
| Nom de champ | Taper | Description |
|---|---|---|
| modèle | string | Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. |
| maxitems | integer | Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. |
| rédacteurs | integer | Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. |
| unique | boolean | Voir https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. |
Vous pouvez ajouter des descriptions couvrant plusieurs lignes dans la description générale de l'API ou des parcours de définitions comme ainsi:
// @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"`
} Vous pouvez déclarer vos structures de réponse à la demande dans un corps de fonction. Vous devez suivre la convention de dénomination <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 L'analyseur ne gère que les commentaires de structure à partir de l'attribut @Description . Mais il écrit tous les commentaires sur le terrain en tel quel.
Ainsi, Swagger Doc comme suit:
"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=="`
}Doc Swagger généré comme suit:
"api.MyBinding" : {
"type" :" object ",
"properties" :{
"crt" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
},
"key" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
}
}
} Si vous utilisez des fichiers générés, les balises swaggertype ou swaggerignore peuvent ne pas être possibles.
En passant une cartographie pour Swag avec --overridesFile vous pouvez dire à Swag d'utiliser un type à la place d'un autre partout où il apparaît. Par défaut, si un fichier .swaggo est présent dans le répertoire actuel, il sera utilisé.
Code 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
Les directives possibles sont des commentaires (commençant par // ), replace path/to/a.type path/to/b.type , et skip path/to/a.type .
(Notez que les chemins complets vers tous les types nommés doivent être fournis pour éviter les problèmes lorsque plusieurs packages définissent un type avec le même nom)
Rendu:
"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-"
}Générez Swagger Doc comme suit:
"Account" : {
"type" : "object" ,
"properties" : {
"id" : {
"type" : "string" ,
"x-nullable" : true ,
"x-abc" : "def" ,
"x-omitempty" : false
}
}
} type Resp struct {
Code int
} //@name ResponseInformations générales de l'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 informationChaque opération API.
// @Security ApiKeyAuthFaire ou condition
// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]Faites-le et de l'état
// @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"`
} Par défaut, la commande swag génère une spécification Swagger dans trois types de fichiers / fichiers différents:
Si vous souhaitez limiter un ensemble de types de fichiers qui doivent être générés, vous pouvez utiliser le drapeau --outputTypes (Short -ot ). La valeur par défaut est go,json,yaml - Types de sortie séparés avec la virgule. Pour limiter la sortie uniquement pour go et les fichiers yaml , vous écririez go,yaml . Avec une commande complète qui serait 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 ]{}
}Voir ce fichier pour plus de détails et autres exemples.
# 980 # 1177
Si vos annotations de fanfaronniers ou vos champs de structure contiennent "{{" ou "}}", la génération de modèle échouera très probablement, car ce sont les délimiteurs par défaut pour les modèles GO.
Pour que la génération fonctionne correctement, vous pouvez modifier les délimiteurs par défaut avec -td . Par exemple:
swag init -g http/api.go -td "[[,]]" Le nouveau délimiteur est une chaîne avec le format " <left delimiter> , <right delimiter> ".
Si la structure est définie dans un package de dépendance, utilisez --parseDependency .
Si la structure est définie dans votre projet principal, utilisez --parseInternal .
Si vous souhaitez inclure à la fois interne et à partir des dépendances, utilisez les deux drapeaux
swag init --parseDependency --parseInternal
Ce projet a été inspiré par Yvasiyarov / Swagger, mais nous avons simplifié l'utilisation et ajouté à la prise en charge d'une variété de cadres Web. La source d'image Gopher est Tenntenn / Gopher-Sttickers. Il a des licences Creative Commons Licensing.
Ce projet existe grâce à toutes les personnes qui contribuent. [Contribuer].
Merci à tous nos bailleurs de fonds! [Devenez un bailleur de fonds]
Soutenez ce projet en devenant un sponsor. Votre logo apparaîtra ici avec un lien vers votre site Web. [Devenir sponsor]
