win8 metro风格网站后台管理模板,吉林省延边州建设局网站,呼和浩特住房和城乡建设部网站,东莞开发方案公司文章目录 Swagger安装使用用法项目demoSwagger注释用法通用API信息 swag命令行参数swagger路由配置 Swagger
安装
go get 安装可执行文件需要配合 GOPATH 模式工作。 go get github.com/swaggo/swag/cmd/swag 因为从 Go 1.17 开始#xff0c;在 go mod 模式下通过 go get 下… 文章目录 Swagger安装使用用法项目demoSwagger注释用法通用API信息 swag命令行参数swagger路由配置 Swagger
安装
go get 安装可执行文件需要配合 GOPATH 模式工作。 go get github.com/swaggo/swag/cmd/swag 因为从 Go 1.17 开始在 go mod 模式下通过 go get 下载对应库文件将无法自动编译并安装到 $GOPATH/bin 的路径 所以不再推荐用 go get 来安装可执行文件的方式。可以使用 go install来代替。
go install github.com/swaggo/swag/cmd/swaglatest
使用用法
在你的 API 源代码中添加注释。在你的 Go 项目的根目录下运行 Swag (例如 ~/root/go-project-name)Swag 会解析注释并在 ~/root/go-project-name/docs 目录下生成必要的文件 (docs 文件夹和 docs/doc.go)。 swag init通过运行以下命令在工程中下载 hertz-swagger :
go get github.com/hertz-contrib/swagger
go get github.com/swaggo/files并在你的代码中引用如下代码:
import github.com/hertz-contrib/swagger // hertz-swagger middleware
import github.com/swaggo/files // swagger embed files效果
项目demo
使用过程 使用 hertz-swagger 规则为 api 和主函数添加注释如下所示 使用 swag init 命令来生成文档生成的文档将被存储在docs/目录下。 编译运行你的应用程序之后在 http://localhost:8888/swagger/index.html可以看到 Swagger UI 界面。
完整代码
package mainimport (contextgithub.com/cloudwego/hertz/pkg/appgithub.com/cloudwego/hertz/pkg/app/servergithub.com/hertz-contrib/swagger_ mystudy/docs //该项一定要配置否则会出现访问404swaggerFiles github.com/swaggo/files
)// PingHandler 测试 handler
// Summary 测试 Summary
// Description 测试 Description
// Accept application/json
// Produce application/json
// Router /ping [get]
func PingHandler(c context.Context, ctx *app.RequestContext) {ctx.JSON(200, map[string]string{ping: pong,})
}// title HertzTest
// version 1.0
// description This is a demo using Hertz.// contact.name hertz-contrib
// contact.url https://github.com/onewcode// license.name Apache 2.0
// license.url http://www.apache.org/licenses/LICENSE-2.0.html// host localhost:8888
// BasePath /
// schemes http
func main() {h : server.Default()h.GET(/ping, PingHandler)url : swagger.URL(http://localhost:8888/swagger/doc.json) // The url pointing to API definitionh.GET(/swagger/*any, swagger.WrapHandler(swaggerFiles.Handler, url))h.Spin()
}访问http://localhost:8888/swagger/index.html
效果
Swagger注释用法
通用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/v1
更多请参考 https://github.com/swaggo/swag/blob/master/README_zh-CN.md
swag命令行参数
用参数运行 Swag (全部参数可以通过运行 swag init -h 查看)。
swag init --parseDependency --parseInternal --parseDepth 5 --instanceName swagger选项默认值描述parseInternalfalse解析内部依赖包。parseDependencyfalse解析外部依赖包。parseDepth100解析依赖包深度如果你知道解析结构的深度推荐使用这个参数swag 命令的执行时间会显著减少。instanceName“swagger”swagger 文档的实例名称。如果要在一个 Hertz 路由上部署多个不同的 swagger 实例请确保每个实例有一个唯一的名字。
swagger路由配置
你可以使用不同的配置选项来配置 Swagger。
func main() {h : server.Default()h.GET(/ping, PingHandler)url : swagger.URL(http://localhost:8888/swagger/doc.json) // The url pointing to API definitionh.GET(/swagger/*any, swagger.WrapHandler(swaggerFiles.Handler, url, swagger.DefaultModelsExpandDepth(-1)))h.Spin()
}选项类型默认值描述URLstring“doc.json”指向 API 定义的 URLDocExpansionstring“list”控制操作和标签的默认扩展设置。它可以是 list只展开标签、full展开标签和操作或 none不展开。DeepLinkingbooltrue如果设置为 true可以启用标签和操作的深度链接。更多信息请参见深度链接文档。DefaultModelsExpandDepthint1模型的默认扩展深度设置为 -1 完全隐藏模型。PersistAuthorizationboolfalse如果设置为 true则会持久化保存授权数据在浏览器关闭/刷新时不会丢失。Oauth2DefaultClientIDstring“”如果设置了这个字段它将用于预填 OAuth2 授权对话框的 client_id 字段。
