swag
v1.16.4
? Englisch ∙ 简体中文 ∙ português
SWAG -Konvertiten gehen Anmerkungen zur Prahlerei -Dokumentation 2.0. Wir haben eine Vielzahl von Plugins für beliebte Go -Web -Frameworks erstellt. Auf diese Weise können Sie sich schnell in ein vorhandenes GO -Projekt (mit der UI der Swagger) integrieren.
Fügen Sie Ihrem API -Quellcode Kommentare hinzu, siehe Format für deklarative Kommentare.
Swag einbauen mithilfe:
go install github.com/swaggo/swag/cmd/swag@latestUm aus der Quelle zu bauen, müssen Sie gehen (1.19 oder neuer).
Alternativ können Sie das Docker -Bild ausführen:
docker run --rm -v $( pwd ) :/code ghcr.io/swaggo/swag:latestOder laden Sie eine vorgefertigte Binärdatei von der Release-Seite herunter.
swag init im Stammordner des Projekts aus, der die main.go -Datei enthält. Dadurch werden Ihre Kommentare analysiert und die erforderlichen Dateien generiert ( docs -Ordner und docs/docs.go ). swag init Importieren Sie die generierten docs/docs.go , damit Ihre spezifische Konfiguration init wird. Wenn Ihre allgemeinen API -Anmerkungen nicht in main.go leben, können Sie Swag mit -g -Flagge informieren.
import _ "example-module-name/docs" swag init -g http/api.goswag fmt -Format den Swag -Kommentar. (Bitte upgrade auf die neueste 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)
Suchen Sie hier den Beispielquellcode.
Beenden Sie die Schritte beim Einstieg
swag init , um Swagger 2.0 -Dokumente zu generieren, die folgenden Pakete: import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed filesmain.go Code hinzu: // @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" )
}
//... Zusätzlich können einige allgemeine API -Informationen dynamisch festgelegt werden. Das generierte Codepaket docs exportiert SwaggerInfo -Variable, mit der wir den Titel, die Beschreibung, die Version, den Host und den Basispfad programmgesteuert festlegen können. Beispiel mit 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 -Code hinzu 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 initDie Swag -Kommentare können automatisch formatiert werden, genau wie "Go fmt". Finden Sie hier das Ergebnis der Formatierung.
Verwendung:
swag fmtOrdner ausschließen:
swag fmt -d ./ --exclude ./internal Wenn Sie swag fmt verwenden, müssen Sie sicherstellen, dass Sie einen DOC -Kommentar für die Funktion haben, um die korrekte Formatierung sicherzustellen. Dies ist auf swag fmt -Einrückungs -Swag -Kommentare mit Registerkarten zurückzuführen, die erst nach einem Standard -DOC -Kommentar zulässig sind.
Zum Beispiel verwenden Sie
// 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 ) {Swagger 2.0 Dokument
Beispiel celler/main.go
| Anmerkung | Beschreibung | Beispiel |
|---|---|---|
| Titel | Erforderlich. Der Titel der Anwendung. | // @title Swagger Beispiel API |
| Version | Erforderlich. Bietet die Version der Anwendungs -API. | // @version 1.0 |
| Beschreibung | Eine kurze Beschreibung der Anwendung. | // @Description Dies ist ein Beispielserver -Celler -Server. |
| tag.name | Name eines Tags. | // @tag.name Dies ist der Name des Tags |
| tag.description | Beschreibung des Tags | // @Tag.Description coole Beschreibung |
| tag.docs.url | URL der externen Dokumentation des Tags | // @tag.docs.url https://example.com |
| tag.docs.description | Beschreibung der externen Dokumentation des Tags | // @tag.docs.description Beste Beispieldokumentation |
| Begriffe von Service | Die Nutzungsbedingungen für die API. | // @termsofService http://swagger.io/terms/ |
| Kontakt.name | Die Kontaktinformationen für die exponierte API. | // @contact.Name API -Unterstützung |
| Kontakt.url | Die URL zeigt auf die Kontaktinformationen. Muss im Format einer URL sein. | // @contact.url http://www.swagger.io/support |
| contact.email | Die E -Mail -Adresse der Kontaktperson/Organisation. Muss im Format einer E -Mail -Adresse sein. | // @contact.email [email protected] |
| Lizenz.Name | Erforderlich. Der für die API verwendete Lizenzname. | // @lizenz.name apache 2.0 |
| Lizenz.url | Eine URL für die für die API verwendete Lizenz. Muss im Format einer URL sein. | // @lizenz.url http://www.apache.org/licenses/license-2.0.html |
| Gastgeber | Der Host (Name oder IP), der die API bedient. | // @host localhost: 8080 |
| Basepath | Der Grundweg, auf dem die API serviert wird. | // @basepath/api/v1 |
| akzeptieren | Eine Liste von MIME -Typen, die die APIs konsumieren können. Beachten Sie, dass Akzeptanz die Operationen mit einer Anforderungsbehörde wie Post, Put und Patch beeinflusst. Der Wert muss wie unter MIME -Typen beschrieben sein. | // @accept json |
| produzieren | Eine Liste von MIME -Typen, die die APIs erzeugen können. Der Wert muss wie unter MIME -Typen beschrieben sein. | // @Produce JSON |
| query.collection.format | Das Paramformat für Standardsammlung (Array) in Abfrage, Enums: CSV, Multi, Pipes, TSV, SSV. Wenn nicht festgelegt, ist CSV der Standard. | // @query.collection.format multi |
| Pläne | Das Transferprotokoll für den Betrieb, der durch Leerzeichen getrennt ist. | // @schemes http https |
| externaldocs.description | Beschreibung des externen Dokuments. | // @externaldocs.description openAPI |
| externaldocs.url | URL des externen Dokuments. | // @externaldocs.url https://swagger.io/resources/open-api/ |
| x-name | Der Erweiterungsschlüssel muss mit X- begonnen und nur JSON-Wert nehmen | // @x-example-key {"key": "value"} |
Wenn eine kurze Zeichenfolge in Ihrer Dokumentation nicht ausreicht oder Sie Bilder, Codebeispiele und solche Dinge benötigen, möchten Sie möglicherweise Markdown -Beschreibungen verwenden. Um Markdown -Beschreibungen zu verwenden, verwenden Sie die folgenden Anmerkungen.
| Anmerkung | Beschreibung | Beispiel |
|---|---|---|
| Titel | Erforderlich. Der Titel der Anwendung. | // @title Swagger Beispiel API |
| Version | Erforderlich. Bietet die Version der Anwendungs -API. | // @version 1.0 |
| Beschreibung.Markdown | Eine kurze Beschreibung der Anwendung. Analysiert aus der API.MD -Datei. Dies ist eine Alternative zu @Description | // @Beschreibung.Markdown Kein Wert benötigt, dies analysiert die Beschreibung von api.md |
| tag.name | Name eines Tags. | // @tag.name Dies ist der Name des Tags |
| tag.description.markdown | Beschreibung des Tags Dies ist eine Alternative zu Tag.Description. Die Beschreibung wird aus einer Datei mit dem Namen tagname.md gelesen | // @tag.description.markdown |
| tag.x-name | Der Erweiterungsschlüssel muss mit X- und nur den String-Wert einnehmen | // @X-Example-Key-Wert |
Beispiel Celler/Controller
| Anmerkung | Beschreibung |
|---|---|
| Beschreibung | Eine ausführliche Erklärung des Betriebsverhaltens. |
| Beschreibung.Markdown | Eine kurze Beschreibung der Anwendung. Die Beschreibung wird aus einer Datei gelesen. EG @description.markdown details werden details.md geladen |
| Ausweis | Eine eindeutige Zeichenfolge, die zur Identifizierung des Vorgangs verwendet wird. Muss unter allen API -Operationen einzigartig sein. |
| Tags | Eine Liste von Tags für jede API -Operation, die durch Kommas getrennt ist. |
| Zusammenfassung | Eine kurze Zusammenfassung dessen, was die Operation tut. |
| akzeptieren | Eine Liste von MIME -Typen, die die APIs konsumieren können. Beachten Sie, dass Akzeptanz die Operationen mit einer Anforderungsbehörde wie Post, Put und Patch beeinflusst. Der Wert muss wie unter MIME -Typen beschrieben sein. |
| produzieren | Eine Liste von MIME -Typen, die die APIs erzeugen können. Der Wert muss wie unter MIME -Typen beschrieben sein. |
| Param | Parameter, die durch Leerzeichen getrennt sind. param name , param type , data type , is mandatory? , comment attribute(optional) |
| Sicherheit | Sicherheit für jede API -Operation. |
| Erfolg | Erfolgsreaktion, die durch Leerzeichen getrennt wurden. return code or default , {param type} , data type , comment |
| Versagen | Versagensantwort, die durch Leerzeichen getrennt wurde. return code or default , {param type} , data type , comment |
| Antwort | Als success und failure |
| Kopfball | Header als Reaktion, die durch Räume getrennt war. return code , {param type} , data type , comment |
| Router | Pfaddefinition, die durch Leerzeichen getrennt wurde. path , [httpMethod] |
| Verabreichter Router | Wie Router, aber veraltet. |
| x-name | Der Erweiterungsschlüssel muss mit X- und nur JSON-Wert einnehmen. |
| X-Codesample | Optionale Markennutzung. Nehmen Sie file als Parameter. Dadurch wird dann nach einer Datei gesucht, die wie die Zusammenfassung im angegebenen Ordner benannt ist. |
| veraltet | Markieren Sie den Endpunkt als veraltet. |
swag akzeptiert alle MIME -Typen, die sich im richtigen Format befinden, dh übereinstimmen */* . Außerdem akzeptiert swag auch Aliase für einige MIMIMTypen wie folgt:
| Alias | MIME -Typ |
|---|---|
| JSON | Anwendung/JSON |
| xml | Text/xml |
| schmucklos | Text/einfach |
| html | Text/HTML |
| MPFD | Mehrpartikel/Formdaten |
| X-WWW-Form-Urlencoded | Anwendung/x-www-form-urlencoded |
| JSON-API | Anwendung/VND.API+JSON |
| JSON-Stream | Anwendung/X-Json-Stream |
| Oktettstrom | Anwendung/Oktettstrom |
| png | Bild/PNG |
| JPEG | Bild/JPEG |
| GIF | Bild/GIF |
| Anmerkung | Beschreibung | Parameter | Beispiel |
|---|---|---|---|
| SecurityDefinitions.basic | Basic auth. | // @SecurityDefinitions.basic BasicAuth | |
| SecurityDefinitions.apikey | API Key Auth. | in, Name, Beschreibung | // @SecurityDefinitions.apikey apikeyAuth |
| SecurityDefinitions.OAUTH2.Application | OAuth2 -Anwendungsauth. | Tokenurl, Umfang, Beschreibung | // @SecurityDefinitions.oauth2.Application OAuth2Application |
| SecurityDefinitions.oauth2.implicit | OAuth2 implizite Auth. | Autorisierung, Umfang, Beschreibung | // @SecurityDefinitions.oauth2.implicit oAuth2implicit |
| SecurityDefinitions.oAuth2.Password | OAuth2 Passwort auth. | Tokenurl, Umfang, Beschreibung | // @SecurityDefinitions.oauth2.Password OAuth2Password |
| SecurityDefinitions.OAUTH2.Accesscode | OAuth2 Access Code Auth. | Tokenurl, Authorizationurl, Umfang, Beschreibung | // @SecurityDefinitions.oauth2.Accesscode oAuth2Accesscode |
| Annotation der Parameter | Beispiel |
|---|---|
| In | // @in Header |
| Name | // @Name Autorisierung |
| Tokenurl | // @Tokenurl https://example.com/oauth/token |
| Authorizationurl | // @authorizationurl https://example.com/oauth/authorize |
| Scope.hoge | // @scope.write Grants Schreibzugriff |
| Beschreibung | // @Description OAuth schützt unsere Entitätendpunkte |
// @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)Es funktioniert auch für die Strukturfelder:
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"`
}| Feldname | Typ | Beschreibung |
|---|---|---|
| bestätigen | string | Bestimmt die Validierung für den Parameter. Mögliche Werte sind: required,optional . |
| Standard | * | Deklariert den Wert des Parameters, den der Server verwendet, wenn keiner bereitgestellt wird, z. B. eine "Anzahl", um die Anzahl der Ergebnisse pro Seite zu steuern. Möglicherweise kann dies zu 100 Personen standardmäßig sind, wenn sie nicht vom Client in der Anforderung geliefert werden. (Hinweis: "Standard" hat keine Bedeutung für die erforderlichen Parameter.) Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Im Gegensatz zum JSON -Schema muss dieser Wert dem definierten type für diesen Parameter entsprechen. |
| maximal | number | Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. |
| Minimum | number | Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. |
| Multiple | number | Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. |
| Maxlenlänge | integer | Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1. |
| Minlenlänge | integer | Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2. |
| Aufschwung | [*] | Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1. |
| Format | string | Das Erweiterungsformat für den zuvor genannten type . Weitere Informationen finden Sie unter Datentypformaten. |
| CollectionFormat | string | Bestimmt das Format des Arrays, wenn das Typ -Array verwendet wird. Mögliche Werte sind:
csv . |
| Beispiel | * | Deklariert das Beispiel für den Parameterwert |
| Erweiterungen | string | Erweiterung zu den Parametern hinzufügen. |
| Feldname | Typ | Beschreibung |
|---|---|---|
| Muster | string | Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. |
| Maxitems | integer | Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. |
| Minitems | integer | Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. |
| UniqueItems | boolean | Siehe https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. |
Sie können Beschreibungen hinzufügen, die mehrere Zeilen in der allgemeinen API -Beschreibung oder Routes Definitionen wie SO überspannen:
// @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"`
} Sie können Ihre Anfrage -Antwortstrukturen in einem Funktionskörper deklarieren. Sie müssen der Namenskonvention <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 Der Parser behandelt nur Struktur -Kommentare, beginnend mit @Description -Attribut. Aber es schreibt alle Strukturen Feldkommentare wie es ist.
So erzeugte Swagger Doc wie folgt:
"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=="`
}Erzeugte Swagger -Dokument wie folgt:
"api.MyBinding" : {
"type" :" object ",
"properties" :{
"crt" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
},
"key" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
}
}
} Wenn Sie generierte Dateien verwenden, sind die swaggertype oder swaggerignore -Tags möglicherweise nicht möglich.
Durch das Übergeben einer Kartierung zum Swag mit --overridesFile können Sie Swag angeben, dass er einen Typ anstelle eines anderen verwenden, wo immer er erscheint. Wenn eine .swaggo -Datei im aktuellen Verzeichnis verwendet wird, wird dies standardmäßig verwendet.
Go Code: Code:
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
Mögliche Anweisungen sind Kommentare (beginnend mit // ), replace path/to/a.type path/to/b.type und skip path/to/a.type .
(Beachten Sie, dass die vollständigen Pfade zu den benannten Typen bereitgestellt werden müssen, um Probleme zu vermeiden, wenn mehrere Pakete einen Typ mit demselben Namen definieren.)
Gerendert:
"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-"
}Generieren Sie Prahlerin wie folgt: wie folgt:
"Account" : {
"type" : "object" ,
"properties" : {
"id" : {
"type" : "string" ,
"x-nullable" : true ,
"x-abc" : "def" ,
"x-omitempty" : false
}
}
} type Resp struct {
Code int
} //@name ResponseAllgemeine API -Info.
// @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 informationJede API -Operation.
// @Security ApiKeyAuthMach oder Zustand
// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]Mach es und Zustand
// @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"`
} Standardmäßig generiert der Befehl swag die Swagger -Spezifikation in drei verschiedenen Dateien/Dateitypen:
Wenn Sie eine Reihe von Dateitypen einschränken möchten, die generiert werden sollten, können Sie das Flag --outputTypes (Short -ot ) verwenden. Der Standardwert ist go,json,yaml - Ausgangstypen, die mit Comma getrennt sind. Um die Ausgabe nur go yaml -Dateien zu beschränken, würden Sie go,yaml schreiben. Mit dem vollständigen Befehl, der 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 ]{}
}Weitere Informationen und andere Beispiele finden Sie in dieser Datei.
#980 #1177
Wenn Ihre Swagger -Annotationen oder Strukturfelder "{{" oder "}}" enthalten, fällt höchstwahrscheinlich die Vorlagenerzeugung aus, da dies die Standardgrenzwerte für GO -Vorlagen sind.
Damit die Generation ordnungsgemäß funktioniert, können Sie die Standardgrenzwerte mit -td ändern. Zum Beispiel:
swag init -g http/api.go -td "[[,]]" Der Neutrainer ist eine Zeichenfolge mit dem Format " <left delimiter> , <right delimiter> ".
Wenn die Struktur in einem Abhängigkeitspaket definiert ist, verwenden Sie --parseDependency .
Wenn die Struktur in Ihrem Hauptprojekt definiert ist, verwenden Sie --parseInternal .
Wenn Sie sowohl interne als auch aus Abhängigkeiten einbeziehen möchten, verwenden Sie beide Flags
swag init --parseDependency --parseInternal
Dieses Projekt wurde von YVasiyarov/Swagger inspiriert, aber wir haben die Nutzung vereinfacht und eine Vielzahl von Webrahmen unterstützt. Gopher-Bildquelle ist Tenntenn/Gopher-Stickers. Es hat Lizenzen für Creative Commons Lizenzierung.
Dieses Projekt besteht dank aller Menschen, die einen Beitrag leisten. [Beitragen].
Vielen Dank an alle unsere Unterstützer! [Backer werden]
Unterstützen Sie dieses Projekt, indem Sie Sponsor werden. Ihr Logo wird hier mit einem Link zu Ihrer Website angezeigt. [Sponsor werden]
