swag
v1.16.4
? Bahasa Inggris ∙ 简体中文 ∙ Português
SWAG Conversi GO Anotasi ke Dokumentasi Swagger 2.0. Kami telah membuat berbagai plugin untuk kerangka kerja Web yang populer. Ini memungkinkan Anda untuk mengintegrasikan dengan cepat dengan proyek GO yang ada (menggunakan UI Swagger).
Tambahkan komentar ke kode sumber API Anda, lihat format komentar deklaratif.
Instal Swag dengan menggunakan:
go install github.com/swaggo/swag/cmd/swag@latestUntuk membangun dari sumber, Anda perlu pergi (1.19 atau lebih baru).
Atau Anda dapat menjalankan gambar Docker:
docker run --rm -v $( pwd ) :/code ghcr.io/swaggo/swag:latestAtau unduh biner yang telah dikompilasi sebelumnya dari halaman rilis.
swag init di folder root proyek yang berisi file main.go Ini akan mengurai komentar Anda dan menghasilkan file yang diperlukan (folder docs dan docs/docs.go ). swag init Pastikan untuk mengimpor docs/docs.go yang dihasilkan sehingga konfigurasi spesifik Anda dapat init . Jika anotasi API umum Anda tidak hidup di main.go , Anda dapat memberi tahu barang curian dengan -g bendera.
import _ "example-module-name/docs" swag init -g http/api.goswag fmt komentar barang curian. (Harap tingkatkan ke versi terbaru) 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)
Temukan kode sumber contoh di sini.
Selesaikan langkah -langkah untuk memulai
swag init untuk menghasilkan dokumen Swagger 2.0, impor paket berikut: import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed filesmain.go Code: // @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" )
}
//... Selain itu, beberapa info API umum dapat diatur secara dinamis. Paket kode yang dihasilkan, docs mengekspor variabel SwaggerInfo yang dapat kita gunakan untuk mengatur judul, deskripsi, versi, host, dan jalur dasar secara terprogram. Contoh Menggunakan 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 initKomentar barang curian dapat diformat secara otomatis, seperti 'go fmt'. Temukan hasil pemformatan di sini.
Penggunaan:
swag fmtKecualikan folder ：
swag fmt -d ./ --exclude ./internal Saat menggunakan swag fmt , Anda perlu memastikan bahwa Anda memiliki komentar DOC untuk fungsi untuk memastikan pemformatan yang benar. Ini karena swag fmt yang mengindir komentar barang curian dengan tab, yang hanya diizinkan setelah komentar DOC standar.
Misalnya, gunakan
// 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 ) {Dokumen Swagger 2.0
Contoh celler/main.go
| anotasi | keterangan | contoh |
|---|---|---|
| judul | Diperlukan. Judul aplikasi. | // @title swagger contoh API |
| versi | Diperlukan. Memberikan versi Aplikasi API. | // @Version 1.0 |
| keterangan | Deskripsi singkat dari aplikasi. | // @Description Ini adalah server Celler Celler Sample. |
| tag.name | Nama tag. | // @tag.name Ini adalah nama tag |
| tag.description | Deskripsi Tag | // @tag.description Deskripsi keren |
| tag.docs.url | URL dokumentasi eksternal tag | // @tag.docs.url https://example.com |
| tag.docs.description | Deskripsi dokumentasi eksternal tag | // @tag.docs.description Dokumentasi contoh terbaik |
| istilah layanan | Ketentuan Layanan untuk API. | // @termsofservice http://swagger.io/terms/ |
| contact.name | Informasi kontak untuk API yang diekspos. | // @contact.name Dukungan API |
| contact.url | URL menunjuk ke informasi kontak. Harus dalam format URL. | // @contact.url http://www.swagger.io/support |
| contact.email | Alamat email orang/organisasi kontak. Harus dalam format alamat email. | // @contact.email [email protected] |
| lisensi.name | Diperlukan. Nama lisensi yang digunakan untuk API. | // @lisensi.name Apache 2.0 |
| lisensi.url | URL ke lisensi yang digunakan untuk API. Harus dalam format URL. | // @lisensi.url http://www.apache.org/licenses/license-2.0.html |
| tuan rumah | Host (nama atau IP) melayani API. | // @host localhost: 8080 |
| Basepath | Jalur dasar tempat API disajikan. | // @Basepath/API/V1 |
| menerima | Daftar tipe mime yang dapat dikonsumsi oleh API. Perhatikan bahwa menerima hanya memengaruhi operasi dengan badan permintaan, seperti pos, put dan patch. Nilai harus seperti yang dijelaskan dalam jenis MIME. | // @cepcept json |
| menghasilkan | Daftar tipe mime yang dapat dihasilkan oleh API. Nilai harus seperti yang dijelaskan dalam jenis MIME. | // @produce json |
| query.collection.format | Koleksi default (array) format param dalam kueri, enum: CSV, multi, pipa, TSV, SSV. Jika tidak diatur, CSV adalah default. | // @query.collection.format multi |
| skema | Protokol transfer untuk operasi yang dipisahkan oleh spasi. | // @schemes http https |
| Externaldocs.Description | Deskripsi dokumen eksternal. | // @externaldocs.description OpenAPI |
| externaldocs.url | URL dokumen eksternal. | // @externaldocs.url https://swagger.io/resources/open-api/ |
| x-name | Kunci ekstensi, harus dimulai dengan X- dan hanya mengambil nilai JSON | // @x-example-key {"key": "value"} |
Ketika string pendek dalam dokumentasi Anda tidak mencukupi, atau Anda memerlukan gambar, contoh kode dan hal -hal seperti itu Anda mungkin ingin menggunakan deskripsi penurunan harga. Untuk menggunakan deskripsi penurunan harga, gunakan anotasi berikut.
| anotasi | keterangan | contoh |
|---|---|---|
| judul | Diperlukan. Judul aplikasi. | // @title swagger contoh API |
| versi | Diperlukan. Memberikan versi Aplikasi API. | // @Version 1.0 |
| deskripsi.markdown | Deskripsi singkat dari aplikasi. Diurai dari file API.MD. Ini adalah alternatif untuk @description | // @description.markdown Tidak ada nilai yang diperlukan, ini menguraikan deskripsi dari API.MD |
| tag.name | Nama tag. | // @tag.name Ini adalah nama tag |
| tag.description.markdown | Deskripsi Tag Ini adalah alternatif untuk Tag.Description. Deskripsi akan dibaca dari file bernama seperti tagname.md | // @tag.description.markdown |
| tag.x-name | Kunci ekstensi, harus dimulai dengan x- dan hanya mengambil nilai string | // @x-example-kunci nilai |
Contoh celler/controller
| anotasi | keterangan |
|---|---|
| keterangan | Penjelasan verbose tentang perilaku operasi. |
| deskripsi.markdown | Deskripsi singkat dari aplikasi. Deskripsi akan dibaca dari file. Misalnya @description.markdown details akan memuat details.md |
| pengenal | String unik yang digunakan untuk mengidentifikasi operasi. Harus unik di antara semua operasi API. |
| tag | Daftar tag untuk setiap operasi API yang dipisahkan oleh koma. |
| ringkasan | Ringkasan singkat dari apa yang dilakukan operasinya. |
| menerima | Daftar tipe mime yang dapat dikonsumsi oleh API. Perhatikan bahwa menerima hanya memengaruhi operasi dengan badan permintaan, seperti pos, put dan patch. Nilai harus seperti yang dijelaskan dalam jenis MIME. |
| menghasilkan | Daftar tipe mime yang dapat dihasilkan oleh API. Nilai harus seperti yang dijelaskan dalam jenis MIME. |
| param | Parameter yang dipisahkan oleh spasi. param name , param type , data type , is mandatory? , attribute(optional) comment (opsional) |
| keamanan | Keamanan untuk setiap operasi API. |
| kesuksesan | Respons keberhasilan yang dipisahkan oleh spasi. return code or default , {param type} , data type , comment |
| kegagalan | Respon kegagalan yang dipisahkan oleh spasi. return code or default , {param type} , data type , comment |
| tanggapan | Sama seperti success dan failure |
| header | Header sebagai tanggapan yang dipisahkan oleh ruang. return code , {param type} , data type , comment |
| router | Definisi jalur yang dipisahkan oleh spasi. path , [httpMethod] |
| Router yang sudah usang | Sama seperti router, tetapi sudah usang. |
| x-name | Kunci ekstensi, harus dimulai dengan X- dan hanya mengambil nilai JSON. |
| X-CodeSample | Penggunaan Markdown Opsional. Ambil file sebagai parameter. Ini kemudian akan mencari file bernama seperti ringkasan di folder yang diberikan. |
| Tercerahkan | Tandai titik akhir sebagai sudah usang. |
swag menerima semua tipe Mime yang berada dalam format yang benar, yaitu, cocok */* . Selain itu, swag juga menerima alias untuk beberapa jenis pantomim sebagai berikut:
| Alias | Jenis pantomim |
|---|---|
| json | Aplikasi/JSON |
| xml | Teks/XML |
| polos | teks/polos |
| html | Teks/html |
| mpfd | multipart/form-data |
| X-WWW-Form-Urlencoded | Aplikasi/X-WWW-Form-Urlencoded |
| JSON-API | Aplikasi/VND.API+JSON |
| JSON-stream | Aplikasi/x-json-stream |
| Octet-stream | Aplikasi/Octet-Stream |
| png | gambar/png |
| jpeg | Gambar/JPEG |
| gif | gambar/gif |
| anotasi | keterangan | parameter | contoh |
|---|---|---|---|
| SecurityDefinitions.Basic | Auth Dasar. | // @SecurityDefinitionss.Basic BasicAuth | |
| SecurityDefinitions.Apikey | API Key Auth. | Dalam, nama, deskripsi | // @SecurityDefinitions.APikey Apikeyauth |
| SecurityDefinitions.OAuth2.Application | OAuth2 Application Auth. | Tokenurl, ruang lingkup, deskripsi | // @SecurityDefinitions.OAuth2.Application OAuth2Application |
| SecurityDefinitions.OAuth2.Implicit | OAuth2 Auth Implisit. | Otorisasi, ruang lingkup, deskripsi | // @SecurityDefinitions.OAuth2.Implicit OAuth2Implicit |
| SecurityDefinitions.OAuth2.password | OAUTH2 AWASTER AUTH. | Tokenurl, ruang lingkup, deskripsi | // @SecurityDefinitions.OAuth2.password oauth2password |
| SecurityDefinitions.OAuth2.AccessCode | OAuth2 Access Code Auth. | Tokenurl, otorisasi, ruang lingkup, deskripsi | // @SecurityDefinitions.OAuth2.AccessCode OAuth2AccessCode |
| Parameter Anotasi | contoh |
|---|---|
| di dalam | // header @in |
| nama | // @name otorisasi |
| tokenurl | // @tokenurl https://example.com/oauth/token |
| Otorisasiurl | // @authorizationUrl https://example.com/oauth/authorize |
| scope.hoge | // @scope.write hibah akses menulis |
| keterangan | // @description oAuth melindungi titik akhir entitas kami |
// @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)Ini juga berfungsi untuk bidang struct:
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"`
}| Nama Lapangan | Jenis | Keterangan |
|---|---|---|
| mengesahkan | string | Menentukan validasi untuk parameter. Nilai yang mungkin adalah: required,optional . |
| bawaan | * | Menyatakan nilai parameter yang akan digunakan server jika tidak ada yang disediakan, misalnya "hitungan" untuk mengontrol jumlah hasil per halaman mungkin default ke 100 jika tidak disediakan oleh klien dalam permintaan. (Catatan: "Default" tidak memiliki arti untuk parameter yang diperlukan.) Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Tidak seperti skema JSON, nilai ini harus sesuai dengan type yang ditentukan untuk parameter ini. |
| maksimum | number | Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. |
| minimum | number | Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. |
| multipel | number | Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. |
| Maxlength | integer | Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1. |
| Minlength | integer | Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2. |
| enum | [*] | Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1. |
| format | string | Format perpanjangan untuk type yang disebutkan sebelumnya. Lihat format tipe data untuk perincian lebih lanjut. |
| CollectionFormat | string | Menentukan format array jika tipe array digunakan. Nilai yang mungkin adalah:
csv . |
| contoh | * | Menyatakan contoh untuk nilai parameter |
| ekstensi | string | Tambahkan ekstensi ke parameter. |
| Nama Lapangan | Jenis | Keterangan |
|---|---|---|
| pola | string | Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. |
| MaxItems | integer | Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. |
| minitem | integer | Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. |
| unikitem | boolean | Lihat https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. |
Anda dapat menambahkan deskripsi yang mencakup beberapa baris di deskripsi API umum atau definisi rute seperti demikian:
// @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"`
} Anda dapat mendeklarasikan struct respons permintaan Anda di dalam badan fungsi. Anda harus mengikuti konvensi penamaan <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 Parser hanya menangani komentar struct yang dimulai dengan atribut @Description . Tapi itu menulis semua komentar bidang struct apa adanya.
Jadi, Dokter Swagger yang dihasilkan sebagai berikut:
"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=="`
}Dokumen Swagger yang dihasilkan sebagai berikut:
"api.MyBinding" : {
"type" :" object ",
"properties" :{
"crt" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
},
"key" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
}
}
} Jika Anda menggunakan file yang dihasilkan, tag swaggertype atau swaggerignore tidak mungkin.
Dengan melewati pemetaan untuk barang curian dengan --overridesFile Anda dapat memberi tahu barang curian untuk menggunakan satu jenis di tempat lain di mana pun itu muncul. Secara default, jika file .swaggo hadir di direktori saat ini akan digunakan.
Kode 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
Arahan yang mungkin adalah komentar (dimulai dengan // ), replace path/to/a.type path/to/b.type , dan skip path/to/a.type .
(Perhatikan bahwa jalur lengkap ke jenis yang disebutkan harus disediakan untuk mencegah masalah ketika beberapa paket menentukan jenis dengan nama yang sama)
Diterjemahkan:
"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-"
}Hasilkan Swagger Doc sebagai berikut:
"Account" : {
"type" : "object" ,
"properties" : {
"id" : {
"type" : "string" ,
"x-nullable" : true ,
"x-abc" : "def" ,
"x-omitempty" : false
}
}
} type Resp struct {
Code int
} //@name ResponseInfo API Umum.
// @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 informationSetiap operasi API.
// @Security ApiKeyAuthBuat atau kondisinya
// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]Buat dan kondisinya
// @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"`
} Perintah Default swag Default menghasilkan spesifikasi Swagger dalam tiga file/jenis file yang berbeda:
Jika Anda ingin membatasi satu set jenis file yang harus dihasilkan, Anda dapat menggunakan --outputTypes (pendek -ot ). Nilai default adalah go,json,yaml - Jenis output dipisahkan dengan koma. Untuk membatasi output hanya untuk go dan file yaml , Anda akan menulis go,yaml . Dengan perintah lengkap yang akan menjadi 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 ]{}
}Lihat file ini untuk detail lebih lanjut dan contoh lainnya.
#980 #1177
Jika anotasi atau bidang struktural Anda mengandung "{{" atau "}}", generasi templat kemungkinan besar akan gagal, karena ini adalah pembatas default untuk template Go.
Untuk membuat generasi berfungsi dengan baik, Anda dapat mengubah pembatas default dengan -td . Misalnya:
swag init -g http/api.go -td "[[,]]" Pembatas baru adalah string dengan format " <left delimiter> , <right delimiter> ".
Jika struct didefinisikan dalam paket ketergantungan, gunakan --parseDependency .
Jika struct didefinisikan dalam proyek utama Anda, gunakan --parseInternal .
Jika Anda ingin memasukkan kedua dan dari dependensi, gunakan kedua bendera
swag init --parseDependency --parseInternal
Proyek ini terinspirasi oleh Yvasiyarov/Swagger tetapi kami menyederhanakan penggunaan dan menambahkan dukungan berbagai kerangka kerja web. Sumber gambar gopher adalah tntenn/gopher-stickers. Ini memiliki lisensi Lisensi Creative Commons.
Proyek ini ada berkat semua orang yang berkontribusi. [Menyumbang].
Terima kasih untuk semua pendukung kami! [Menjadi pendukung]
Dukung proyek ini dengan menjadi sponsor. Logo Anda akan muncul di sini dengan tautan ke situs web Anda. [Menjadi sponsor]
