swag
v1.16.4
？英語∙∙português
SWAGは、Annotationsをswaggerドキュメント2.0に変換します。人気のあるGo Webフレームワーク用のさまざまなプラグインを作成しました。これにより、既存のGOプロジェクト（Swagger UIを使用）とすばやく統合できます。
APIソースコードにコメントを追加します。宣言的なコメント形式を参照してください。
使用してswagをインストールします。
go install github.com/swaggo/swag/cmd/swag@latestソースから構築するには、GO（1.19以降）が必要です。
または、Docker画像を実行できます。
docker run --rm -v $( pwd ) :/code ghcr.io/swaggo/swag:latestまたは、リリースページから事前にコンパイルされたバイナリをダウンロードします。
main.goファイルを含むプロジェクトのルートフォルダーでswag initを実行します。これにより、コメントを解析し、必要なファイル（ docsフォルダーとdocs/docs.go ）を生成します。 swag init生成されたdocs/docs.goインポートして、特定の構成がinit 'edになるようにしてください。一般的なAPIアノテーションがmain.goに住んでいない場合は、 -gフラグを使用してSWAGを知らせることができます。
import _ "example-module-name/docs" swag init -g http/api.goswag fmt形式をSWAGコメントに使用します。 （最新バージョンにアップグレードしてください） 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)
ここで、ソースコードのサンプルを見つけます。
開始のステップを完了します
swag init使用してSwagger 2.0ドキュメントを生成した後、次のパッケージをインポートします。 import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed filesmain.goコードに一般的なAPIアノテーションを追加します： // @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" )
}
//...さらに、一部の一般的なAPI情報は動的に設定できます。生成されたコードパッケージdocsタイトル、説明、バージョン、ホスト、ベースパスをプログラムで設定するために使用できるSwaggerInfo変数をエクスポートします。ジンを使用した例：
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コードにAPI操作アノテーションを追加します 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 initswagコメントは、「go fmt」と同じように、自動的にフォーマットできます。ここでフォーマットの結果を見つけてください。
使用法：
swag fmtフォルダを除外する：
swag fmt -d ./ --exclude ./internal swag fmt使用する場合、正しいフォーマットを確保するために、関数についてドキュメントコメントがあることを確認する必要があります。これは、 swag fmtタブで盗品のコメントをインデントするためです。これは、標準のドキュメントコメントの後にのみ許可されています。
たとえば、使用します
// 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ドキュメント
例Celler/main.go
| 注釈 | 説明 | 例 |
|---|---|---|
| タイトル | 必須。アプリケーションのタイトル。 | // @title swaggerの例API |
| バージョン | 必須。アプリケーションAPIのバージョンを提供します。 | // @version 1.0 |
| 説明 | アプリケーションの簡単な説明。 | // @descriptionこれはサンプルサーバーセラーサーバーです。 |
| tag.name | タグの名前。 | // @tag.Nameこれはタグの名前です |
| tag.description | タグの説明 | // @tag.descriptionクールな説明 |
| tag.docs.url | タグの外部ドキュメントのURL | // @tag.docs.url https://example.com |
| tag.docs.description | タグの外部ドキュメントの説明 | // @tag.docs.description最良の例ドキュメント |
| サービス用語 | APIのサービス条件。 | // @termsofservice http://swagher.io/terms/ |
| contact.name | 露出したAPIの連絡先情報。 | // @contact.Name APIサポート |
| contact.url | 連絡先情報を指しているURL。 URLの形式である必要があります。 | // @contact.url http://www.swagger.io/support |
| contact.email | 連絡先/組織のメールアドレス。メールアドレスの形式でなければなりません。 | // @contact.email [email protected] |
| license.name | 必須。 APIに使用されるライセンス名。 | // @license.name apache 2.0 |
| license.url | APIに使用されるライセンスのURL。 URLの形式である必要があります。 | // @license.url http://www.apache.org/licenses/license-2.0.html |
| ホスト | APIを提供するホスト（名前またはIP）。 | // @host localhost：8080 |
| ベースパス | APIが提供されるベースパス。 | // @basepath/api/v1 |
| 受け入れる | APIが消費できるMIMEタイプのリスト。 Acceptは、Post、Put、Patchなど、リクエスト本体の操作のみにのみ影響することに注意してください。値は、MIMEタイプで説明されているとおりでなければなりません。 | // @accept Json |
| 生産する | APIが生成できるMIMEタイプのリスト。値は、MIMEタイプで説明されているとおりでなければなりません。 | // @Produce JSON |
| query.collection.format | クエリのデフォルトコレクション（配列）パラメート形式、列挙：CSV、マルチ、パイプ、TSV、SSV。設定されていない場合、CSVはデフォルトです。 | // @query.collection.format multi |
| スキーム | 空間で区切られた操作の転送プロトコル。 | // @schemes http https |
| externaldocs.description | 外部ドキュメントの説明。 | // @externaldocs.description openapi |
| externaldocs.url | 外部ドキュメントのURL。 | // @externaldocs.url https://swagher.io/resources/open-api/ |
| x-name | 拡張キーは、x-から開始し、JSON値のみを取得する必要があります | // @x-example-key {"key"： "value"} |
ドキュメントの短い文字列が不十分な場合、または画像、コード例、そのようなものが必要な場合、Markdownの説明を使用することができます。マークダウンの説明を使用するには、次の注釈を使用します。
| 注釈 | 説明 | 例 |
|---|---|---|
| タイトル | 必須。アプリケーションのタイトル。 | // @title swaggerの例API |
| バージョン | 必須。アプリケーションAPIのバージョンを提供します。 | // @version 1.0 |
| Description.MarkDown | アプリケーションの簡単な説明。 API.mdファイルから解析されます。これは@descriptionの代替です | // @description.markdown値は必要ありません、これはapi.mdからの説明を解析します |
| tag.name | タグの名前。 | // @tag.Nameこれはタグの名前です |
| tag.description.markdown | タグの説明これは、tag.descriptionの代替です。説明は、tagname.mdのような名前のファイルから読み取られます | // @tag.description.markdown |
| tag.x-name | 拡張キーは、x-から開始し、文字列値のみを取得する必要があります | // @x-example-key値 |
サンプルセラー/コントローラー
| 注釈 | 説明 |
|---|---|
| 説明 | 操作動作の冗長な説明。 |
| Description.MarkDown | アプリケーションの簡単な説明。説明はファイルから読み取られます。例： @description.markdown details details.mdを読み込みます |
| id | 操作を識別するために使用される一意の文字列。すべてのAPI操作の中で一意でなければなりません。 |
| タグ | コンマで区切られた各API操作のタグのリスト。 |
| まとめ | 操作が行うことの短い要約。 |
| 受け入れる | APIが消費できるMIMEタイプのリスト。 Acceptは、Post、Put、Patchなど、リクエスト本体の操作のみにのみ影響することに注意してください。値は、MIMEタイプで説明されているとおりでなければなりません。 |
| 生産する | APIが生成できるMIMEタイプのリスト。値は、MIMEタイプで説明されているとおりでなければなりません。 |
| パラメーション | スペースで区切られたパラメーター。 param name 、 param type 、 data type 、 is mandatory? 、 comment attribute(optional) |
| 安全 | 各API操作へのセキュリティ。 |
| 成功 | スペースで区切られた成功応答。 return code or default 、 {param type} 、 data type 、 comment |
| 失敗 | スペースで区切られた障害応答。 return code or default 、 {param type} 、 data type 、 comment |
| 応答 | successとfailureと同じ |
| ヘッダ | スペースで区切られたヘッダー。 return code 、 {param type} 、 data type 、 comment |
| ルーター | スペースで区切られたパス定義。 path 、 [httpMethod] |
| DeprecatedRouter | ルーターと同じですが、非推奨です。 |
| x-name | 拡張キーは、x-から開始し、JSON値のみを取得する必要があります。 |
| X-コードサンプル | オプションのマークダウンの使用。パラメーターとしてfile取得します。これにより、指定されたフォルダーの要約のような名前のファイルが検索されます。 |
| 非推奨 | エンドポイントを非推奨にマークします。 |
swag 、正しい形式のすべてのMIMEタイプ、つまりマッチ*/*を受け入れます。それに加えて、 swag次のように、いくつかのMIMEタイプのエイリアスも受け入れます。
| エイリアス | MIMEタイプ |
|---|---|
| JSON | アプリケーション/JSON |
| XML | テキスト/XML |
| 無地 | テキスト/プレーン |
| HTML | テキスト/HTML |
| MPFD | MultiPart/Form-Data |
| x-www-form-urlencoded | アプリケーション/x-www-form-urlencoded |
| JSON-API | アプリケーション/vnd.api+json |
| json-stream | アプリケーション/x-json-stream |
| オクテットストリーム | アプリケーション/オクテットストリーム |
| PNG | 画像/PNG |
| jpeg | 画像/jpeg |
| gif | 画像/gif |
| 注釈 | 説明 | パラメーター | 例 |
|---|---|---|---|
| SecurityDefinitions.Basic | 基本的な認証。 | // @SecurityDefinitions.Basic BasicAuth | |
| SecurityDefinitions.apikey | APIキー認証。 | で、名前、説明 | // @securitydefinitions.apikey apikeyauth |
| SecurityDefinitions.oauth2.Application | OAUTH2アプリケーションAUTH。 | Tokenurl、スコープ、説明 | // @securitydefinitions.oauth2.application oauth2Application |
| SecurityDefinitions.oauth2.Implicit | OAUTH2暗黙の認証。 | authorizationurl、範囲、説明 | // @securitydefinitions.oauth2.implicit oauth2implicit |
| SecurityDefinitions.oauth2.password | OAUTH2パスワード認証。 | Tokenurl、スコープ、説明 | // @securitydefinitions.oauth2.password oauth2password |
| SecurityDefinitions.oauth2.AccessCode | OAUTH2アクセスコードAUTH。 | tokenurl、authorizationurl、scope、description | // @securitydefinitions.oauth2.accessCode oauth2AccessCode |
| パラメーター注釈 | 例 |
|---|---|
| で | // @inヘッダー |
| 名前 | // @Name Authorization |
| Tokenurl | // @tokenurl https://example.com/oauth/token |
| AuthorizationUrl | // @authorizationurl https://example.com/oauth/authorize |
| scope.hoge | // @scope.writeグラント書き込みアクセス |
| 説明 | // @description oauthはエンティティエンドポイントを保護します |
// @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)また、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"`
}| フィールド名 | タイプ | 説明 |
|---|---|---|
| 検証します | string | パラメーターの検証を決定します。考えられる値は次のとおりです。 required,optional 。 |
| デフォルト | * | リクエストでクライアントが提供しない場合、ページごとの結果の数を制御する「カウント」を制御する「カウント」が提供されていない場合、サーバーが使用するパラメーターの値を宣言します。 （注：「デフォルト」には、必要なパラメーターに意味がありません。）https：//tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2を参照してください。 JSONスキーマとは異なり、この値はこのパラメーターの定義typeに準拠する必要があります。 |
| 最大 | number | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2を参照してください。 |
| 最小 | number | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3を参照してください。 |
| 複数 | number | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1を参照してください。 |
| 最大長 | integer | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1を参照してください。 |
| minlength | integer | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2を参照してください。 |
| 酵素 | [*] | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1を参照してください。 |
| 形式 | string | 前述のtypeの拡張形式。詳細については、データ型形式を参照してください。 |
| CollectionFormat | string | タイプ配列が使用される場合は、配列の形式を決定します。考えられる値は次のとおりです。
csvです。 |
| 例 | * | パラメーター値の例を宣言します |
| 拡張機能 | string | パラメーターに拡張機能を追加します。 |
| フィールド名 | タイプ | 説明 |
|---|---|---|
| パターン | string | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3を参照してください。 |
| MAXITEMS | integer | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2を参照してください。 |
| minitems | integer | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3を参照してください。 |
| uniqueItems | boolean | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4を参照してください。 |
次のような一般的なAPI説明またはルート定義のいずれかに複数の行にまたがる説明を追加できます。
// @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"`
}関数本文内のリクエスト応答構造を宣言できます。命名条約<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パーサーは、 @Description属性から始まるstructコメントのみを処理します。しかし、それはすべてのstructフィールドコメントをそのまま書き込みます。
したがって、次のようにSwaggerドキュメントを生成しました：
"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：
"api.MyBinding" : {
"type" :" object ",
"properties" :{
"crt" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
},
"key" :{
"type" :" string ",
"format" :" base64 ",
"example" :" U3dhZ2dlciByb2Nrcw == "
}
}
}生成されたファイルを使用している場合、 swaggertypeまたはswaggerignoreタグが不可能な場合があります。
マッピングをSWAGに渡すことにより、 --overridesFileは、どこにいても別のタイプの代わりに1つのタイプを使用するようにSWAGに指示できます。デフォルトでは、現在のディレクトリに.swaggoファイルが存在する場合、使用されます。
コードに行く：
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
考えられるディレクティブは、コメント（ //から始まる）、 replace path/to/a.type path/to/b.type 、 skip path/to/a.type 。
（複数のパッケージが同じ名前のタイプを定義する場合、問題を防ぐために、名前付きタイプへのフルパスを提供する必要があることに注意してください）
レンダリング：
"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-"
}次のようにswagger docを生成します：
"Account" : {
"type" : "object" ,
"properties" : {
"id" : {
"type" : "string" ,
"x-nullable" : true ,
"x-abc" : "def" ,
"x-omitempty" : false
}
}
} type Resp struct {
Code int
} //@name Response一般的な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 information各API操作。
// @Security ApiKeyAuthそれを作るか状態にします
// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]それと状態にします
// @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"`
}デフォルトでは、 swagコマンドが3つの異なるファイル/ファイルタイプでSwagger仕様を生成します。
生成する必要があるファイルタイプのセットを制限する場合は、 --outputTypes （Short -ot ）フラグを使用できます。デフォルト値はgo,json,yamlカンマで分離された出力タイプです。 goとyamlファイルのみに出力を制限するには、 go,yaml書き込みます。 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 ]{}
}詳細やその他の例については、このファイルを参照してください。
＃980＃1177
swaggerアノテーションまたは構造体フィールドに「{{{"または"}}」が含まれている場合、テンプレートの生成はおそらく失敗します。
生成を適切に機能させるには、Default Delimitersを-tdで変更できます。例えば：
swag init -g http/api.go -td "[[,]]"新しいデリミターは、フォーマット「 <left delimiter> 、 <right delimiter> 」を備えた文字列です。
structが依存関係パッケージで定義されている場合は、 --parseDependencyを使用します。
構造体がメインプロジェクトで定義されている場合は、 --parseInternalを使用してください。
内部と依存関係の両方を含めたい場合は、両方のフラグを使用します
swag init --parseDependency --parseInternal
このプロジェクトはYvasiyarov/Swaggerに触発されましたが、使用法を簡素化し、さまざまなWebフレームワークをサポートしました。 Gopher画像ソースはTenntenn/Gopher-Stickersです。 Creative Commonsライセンスのライセンスがあります。
このプロジェクトは、貢献するすべての人々のおかげで存在します。 [貢献する]。
すべての支援者に感謝します！ [支援者になる]
スポンサーになることにより、このプロジェクトをサポートします。あなたのロゴは、あなたのウェブサイトへのリンクでここに表示されます。 [スポンサーになる]
