网站平台优化,大气网站源码下载,仿魔客吧网站模板,珠海网站建设知识swag
Swag将Go的注释转换为Swagger2.0文档。我们为流行的 Go Web Framework 创建了各种插件#xff0c;这样可以与现有Go项目快速集成#xff08;使用Swagger UI#xff09;。
目录
快速开始支持的Web框架如何与Gin集成格式化说明开发现状声明式注释格式 通用API信息API操…swag
Swag将Go的注释转换为Swagger2.0文档。我们为流行的 Go Web Framework 创建了各种插件这样可以与现有Go项目快速集成使用Swagger UI。
目录
快速开始支持的Web框架如何与Gin集成格式化说明开发现状声明式注释格式 通用API信息API操作安全性 样例 多行的描述用户自定义的具有数组类型的结构响应对象中的模型组合在响应中增加头字段使用多路径参数结构体的示例值结构体描述使用swaggertype标签更改字段类型使用swaggerignore标签排除字段将扩展信息添加到结构字段对展示的模型重命名如何使用安全性注释 项目相关
快速开始
将注释添加到API源代码中请参阅声明性注释格式。使用如下命令下载swag
go install github.com/swaggo/swag/cmd/swaglatest从源码开始构建的话需要有Go环境1.18及以上版本。
或者从github的release页面下载预编译好的二进制文件。
在包含main.go文件的项目根目录运行swag init。这将会解析注释并生成需要的文件docs文件夹和docs/docs.go。
swag init确保导入了生成的docs/docs.go文件这样特定的配置文件才会被初始化。如果通用API注释没有写在main.go中可以使用-g标识符来告知swag。
swag init -g http/api.go(可选) 使用fmt格式化 SWAG 注释。(请先升级到最新版本)
swag fmtswag cli
swag init -h
NAME:swag init - Create docs.goUSAGE:swag init [command options] [arguments...]OPTIONS:--generalInfo value, -g value API通用信息所在的go源文件路径如果是相对路径则基于API解析目录 (默认: main.go)--dir value, -d value API解析目录 (默认: ./)--exclude value 解析扫描时排除的目录多个目录可用逗号分隔默认空--propertyStrategy value, -p value 结构体字段命名规则三种snakecase,camelcase,pascalcase (默认: camelcase)--output value, -o value 文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: ./docs)--parseVendor 是否解析vendor目录里的go源文件默认不--parseDependency 是否解析依赖目录中的go源文件默认不--markdownFiles value, --md value 指定API的描述信息所使用的markdown文件所在的目录--generatedTime 是否输出时间到输出文件docs.go的顶部默认是--codeExampleFiles value, --cef value 解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹默认禁用--parseInternal 解析 internal 包中的go文件默认禁用--parseDepth value 依赖解析深度 (默认: 100)--instanceName value 设置文档实例名 (默认: swagger)swag fmt -h
NAME:swag fmt - format swag commentsUSAGE:swag fmt [command options] [arguments...]OPTIONS:--dir value, -d value API解析目录 (默认: ./)--exclude value 解析扫描时排除的目录多个目录可用逗号分隔默认空--generalInfo value, -g value API通用信息所在的go源文件路径如果是相对路径则基于API解析目录 (默认: main.go)--help, -h show help (default: false)
支持的Web框架
ginechobuffalonet/httpgorilla/muxgo-chi/chiflamingofiberatreugohertz
如何与Gin集成
点击此处查看示例源代码。
使用swag init生成Swagger2.0文档后导入如下代码包
import github.com/swaggo/gin-swagger // gin-swagger middleware
import github.com/swaggo/files // swagger embed files在main.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 supportswagger.io// 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变量使用该变量可以通过编码的方式设置标题、描述、版本、主机和基础路径。使用Gin的示例
package mainimport (github.com/gin-gonic/gingithub.com/swaggo/filesgithub.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 supportswagger.io// license.name Apache 2.0
// license.url http://www.apache.org/licenses/LICENSE-2.0.html
func main() {// programatically set swagger infodocs.SwaggerInfo.Title Swagger Example APIdocs.SwaggerInfo.Description This is a sample server Petstore server.docs.SwaggerInfo.Version 1.0docs.SwaggerInfo.Host petstore.swagger.iodocs.SwaggerInfo.BasePath /v2docs.SwaggerInfo.Schemes []string{http, https}r : gin.New()// use ginSwagger middleware to serve the API docsr.GET(/swagger/*any, ginSwagger.WrapHandler(swaggerFiles.Handler))r.Run()
}在controller代码中添加API操作注释
package controllerimport (fmtnet/httpstrconvgithub.com/gin-gonic/gingithub.com/swaggo/swag/example/celler/httputilgithub.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 init运行程序然后在浏览器中访问 http://localhost:8080/swagger/index.html 。将看到Swagger 2.0 Api文档如下所示 格式化说明
可以针对Swag的注释自动格式化就像go fmt。 此处查看格式化结果 here.
示例
swag fmt排除目录不扫描示例
swag fmt -d ./ --exclude ./internal开发现状
Swagger 2.0 文档 Basic Structure API Host and Base Path Paths and Operations Describing Parameters Describing Request Body Describing Responses MIME Types Authentication Basic Authentication API Keys Adding Examples File Upload Enums Grouping Operations With Tags Swagger Extensions
声明式注释格式
通用API信息
示例 celler/main.go
注释说明示例title必填 应用程序的名称。// title Swagger Example APIversion必填 提供应用程序API的版本。// version 1.0description应用程序的简短描述。// description This is a sample server celler server.tag.name标签的名称。// tag.name This is the name of the tagtag.description标签的描述。// tag.description Cool Descriptiontag.docs.url标签的外部文档的URL。// tag.docs.url https://example.comtag.docs.description标签的外部文档说明。// tag.docs.description Best example documentationtermsOfServiceAPI的服务条款。// termsOfService http://swagger.io/terms/contact.name公开的API的联系信息。// contact.name API Supportcontact.url联系信息的URL。 必须采用网址格式。// contact.url http://www.swagger.io/supportcontact.email联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。// contact.email supportswagger.iolicense.name必填 用于API的许可证名称。// license.name Apache 2.0license.url用于API的许可证的URL。 必须采用网址格式。// license.url http://www.apache.org/licenses/LICENSE-2.0.htmlhost运行API的主机主机名或IP地址。// host localhost:8080BasePath运行API的基本路径。// BasePath /api/v1acceptAPI 可以使用的 MIME 类型列表。 请注意Accept 仅影响具有请求正文的操作例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。// accept jsonproduceAPI可以生成的MIME类型的列表。值必须如“Mime类型”中所述。// produce jsonquery.collection.format请求URI query里数组参数的默认格式csvmultipipestsvssv。 如果未设置则默认为csv。// query.collection.format multischemes用空格分隔的请求的传输协议。// schemes http httpsexternalDocs.descriptionDescription of the external document.// externalDocs.description OpenAPIexternalDocs.urlURL of the external document.// externalDocs.url https://swagger.io/resources/open-api/x-name扩展的键必须以x-开头并且只能使用json值// x-example-key {“key”: “value”}
使用Markdown描述
如果文档中的短字符串不足以完整表达或者需要展示图片代码示例等类似的内容则可能需要使用Markdown描述。要使用Markdown描述请使用一下注释。
注释说明示例title必填 应用程序的名称。// title Swagger Example APIversion必填 提供应用程序API的版本。// version 1.0description.markdown应用程序的简短描述。 从api.md文件中解析。 这是description的替代用法。// description.markdown No value needed, this parses the description from api.mdtag.name标签的名称。// tag.name This is the name of the tagtag.description.markdown标签说明这是tag.description的替代用法。 该描述将从名为tagname.md的文件中读取。// tag.description.markdown
API操作
Example celler/controller
注释描述description操作行为的详细说明。description.markdown应用程序的简短描述。该描述将从名为endpointname.md的文件中读取。id用于标识操作的唯一字符串。在所有API操作中必须唯一。tags每个API操作的标签列表以逗号分隔。summary该操作的简短摘要。acceptAPI 可以使用的 MIME 类型列表。 请注意Accept 仅影响具有请求正文的操作例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。produceAPI可以生成的MIME类型的列表。值必须如“Mime类型”中所述。param用空格分隔的参数。param name,param type,data type,is mandatory?,comment attribute(optional)security每个API操作的安全性。success以空格分隔的成功响应。return code,{param type},data type,commentfailure以空格分隔的故障响应。return code,{param type},data type,commentresponse与success、failure作用相同header以空格分隔的头字段。 return code,{param type},data type,commentrouter以空格分隔的路径定义。 path,[httpMethod]x-name扩展字段必须以x-开头并且只能使用json值。
Mime类型
swag 接受所有格式正确的MIME类型, 即使匹配 */*。除此之外swag还接受某些MIME类型的别名如下所示
AliasMIME Typejsonapplication/jsonxmltext/xmlplaintext/plainhtmltext/htmlmpfdmultipart/form-datax-www-form-urlencodedapplication/x-www-form-urlencodedjson-apiapplication/vnd.apijsonjson-streamapplication/x-json-streamoctet-streamapplication/octet-streampngimage/pngjpegimage/jpeggifimage/gif
参数类型
querypathheaderbodyformData
数据类型
string (string)integer (int, uint, uint32, uint64)number (float32)boolean (bool)user defined struct
安全性
注释描述参数示例securitydefinitions.basicBasic auth.// securityDefinitions.basic BasicAuthsecuritydefinitions.apikeyAPI key auth.in, name// securityDefinitions.apikey ApiKeyAuthsecuritydefinitions.oauth2.applicationOAuth2 application auth.tokenUrl, scope// securitydefinitions.oauth2.application OAuth2Applicationsecuritydefinitions.oauth2.implicitOAuth2 implicit auth.authorizationUrl, scope// securitydefinitions.oauth2.implicit OAuth2Implicitsecuritydefinitions.oauth2.passwordOAuth2 password auth.tokenUrl, scope// securitydefinitions.oauth2.password OAuth2Passwordsecuritydefinitions.oauth2.accessCodeOAuth2 access code auth.tokenUrl, authorizationUrl, scope// securitydefinitions.oauth2.accessCode OAuth2AccessCode
参数注释示例in// in headername// name AuthorizationtokenUrl// tokenUrl https://example.com/oauth/tokenauthorizationurl// authorizationurl https://example.com/oauth/authorizescope.hoge// scope.write Grants write access
属性
// 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 collection query []string false string collection collectionFormat(multi)
// Param extensions query []string false string collection extensions(x-exampletest,x-nullable)也适用于结构体字段
type Foo struct {Bar string minLength:4 maxLength:16Baz int minimum:10 maximum:20 default:15Qux []string enums:foo,bar,baz
}当前可用的
字段名类型描述default*声明如果未提供任何参数则服务器将使用的默认参数值例如如果请求中的客户端未提供该参数则用于控制每页结果数的“计数”可能默认为100。 注意“default”对于必需的参数没有意义。参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2。 与JSON模式不同此值务必符合此参数的定义类型。maximumnumber参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.minimumnumber参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.maxLengthinteger参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.minLengthinteger参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.enums[*]参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.formatstring上面提到的类型的扩展格式。有关更多详细信息请参见数据类型格式。collectionFormatstring指定query数组参数的格式。 可能的值为 csv - 逗号分隔值 foo,bar. ssv - 空格分隔值 foo bar. tsv - 制表符分隔值 foo\tbar. pipes - 管道符分隔值 foo|bar. multi - 对应于多个参数实例而不是单个实例 foobarfoobaz 的多个值。这仅对“query”或“formData”中的参数有效。 默认值是 csv。
进一步的
字段名类型描述multipleOfnumberSee https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.patternstringSee https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.maxItemsintegerSee https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.minItemsintegerSee https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.uniqueItemsbooleanSee 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 modeltype Account struct {ID int json:id example:1Name string json:name example:account name
}响应对象中的模型组合
// JSONResult的data字段类型将被proto.Order类型替换
success 200 {object} jsonresult.JSONResult{dataproto.Order} desctype JSONResult struct {Code int json:code Message string json:messageData interface{} json:data
}type Order struct { //in proto package...
}还支持对象数组和原始类型作为嵌套响应
success 200 {object} jsonresult.JSONResult{data[]proto.Order} desc
success 200 {object} jsonresult.JSONResult{datastring} desc
success 200 {object} jsonresult.JSONResult{data[]string} desc替换多个字段的类型。如果某字段不存在将添加该字段。
success 200 {object} jsonresult.JSONResult{data1string,data2[]string,data3proto.Order,data4[]proto.Order} desc在响应中增加头字段
// 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]结构体的示例值
type Account struct {ID int json:id example:1Name string json:name example:account namePhotoUrls []string json:photo_urls example:http://test/image/1.jpg,http://test/image/2.jpg
}结构体描述
type Account struct {// ID this is useridID int json:idName string json:name // This is Name
}使用swaggertype标签更改字段类型
#201
type TimestampTime struct {time.Time
}///实现encoding.JSON.Marshaler接口
func (t *TimestampTime) MarshalJSON() ([]byte, error) {bin : make([]byte, 16)bin strconv.AppendInt(bin[:0], t.Time.Unix(), 10)return bin, nil
}///实现encoding.JSON.Unmarshaler接口
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 {// 使用swaggertype标签将别名类型更改为内置类型integerID sql.NullInt64 json:id swaggertype:integer// 使用swaggertype标签更改struct类型为内置类型integerRegisterTime TimestampTime json:register_time swaggertype:primitive,integer// Array types can be overridden using array,prim_type formatCoeffs []big.Float json:coeffs swaggertype:array,number
}#379
type CerticateKeyPair struct {Crt []byte json:crt swaggertype:string format:base64 example:U3dhZ2dlciByb2NrcwKey []byte json:key swaggertype:string format:base64 example:U3dhZ2dlciByb2Nrcw
}生成的swagger文档如下
api.MyBinding: {type:object,properties:{crt:{type:string,format:base64,example:U3dhZ2dlciByb2Nrcw},key:{type:string,format:base64,example:U3dhZ2dlciByb2Nrcw}}
}使用swaggerignore标签排除字段
type Account struct {ID string json:idName string json:nameIgnored int swaggerignore:true
}将扩展信息添加到结构字段
type Account struct {ID string json:id extensions:x-nullable,x-abcdef,!x-omitempty // 扩展字段必须以x-开头
}生成swagger文档如下所示
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使用AND条件。
// Security ApiKeyAuth
// Security OAuth2Application[write, admin]
