1.介绍
1.1 什么是swagger
Swagger
是一套用于描述和文档化 RESTful API
的工具。它最初是由 Reverb Technologies
开发的,后来成为了 OpenAPI
规范的一部分。Swagger
提供了一种简单而直观的方式来定义、生成和可视化 API
,帮助开发人员和团队更好地理解和使用 API
。
1.2 swaggo
github.com/swaggo/swag
是一个开源项目,用于在 Go
语言中自动生成 Swagger
文档。它通过解析 Go
代码中的注释,生成符合 OpenAPI
规范的文档,从而简化了 API
文档的生成和维护过程。
源码地址: https://github.com/swaggo/swag,截止到(2024.06.18): Star 10K
主要功能
- 自动生成 Swagger 文档:
swag
可以自动扫描 Go
代码中的注释和类型定义,生成 Swagger
文档。这样开发人员无需手动编写 Swagger
规范文件,减少了重复劳动和出错的可能性。
- 注释驱动: 通过在
Go
代码中添加特定格式的注释,开发人员可以详细描述 API
的端点、请求参数、响应格式、错误码等。swag
工具会解析这些注释并生成相应的文档。
- 支持多种框架:
swag
支持多种流行的 Go Web
框架,如 gin
、echo
、fiber
等。无论使用哪种框架,开发人员都可以轻松集成 swag
并生成 API
文档。
- 嵌入式 Swagger UI: 生成的
Swagger
文档可以通过嵌入式 Swagger UI
页面查看和测试。开发人员可以直接在浏览器中查看API
文档,并进行交互式测试。
2.安装
2.1 下载swag
$ go install github.com/swaggo/swag/cmd/swag@latest
|
2.2 swag init 说明
$ swag init -h
NAME: swag init - Create docs.go
USAGE: swag init [command options] [arguments...]
OPTIONS: --quiet, -q --generalInfo value, -g value --dir value, -d value --exclude value --propertyStrategy value, -p value --output value, -o value --outputTypes value, --ot value --parseVendor --parseDependencyLevel value, --pdl value --parseDependency, --pd --markdownFiles value, --md value --codeExampleFiles value, --cef value --parseInternal --generatedTime --parseDepth value --requiredByDefault --instanceName value --overridesFile value --parseGoList --parseExtension value --tags value, -t value --templateDelims value, --td value --packageName --output --collectionFormat value, --cf value --packagePrefix value --state value
|
3. 快速使用
下面以集成到Gin框架为示例,进行快速入门
3.1 安装依赖
$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files
|
3.2 Swagger封装
import ( "fmt" "github.com/gin-gonic/gin" "52lu/gin-api-template/docs" swaggerFiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" )
func SwaggerInit(engine *gin.Engine) { swaggerInfo := docs.SwaggerInfo swaggerInfo.Title = "GinApiDemo" swaggerInfo.Description = "基于Gin框架,开发api通用框架模版" swaggerInfo.Version = "v1.0.0" swaggerInfo.Host = "0.0.0.0:8800" swaggerInfo.BasePath = "" engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) }
|
3.3 调用函数
...
r := gin.Default() ...
SwaggerInit(r)
|
3.4 接口编写
1.Get接口
type DemoResp struct { Id int64 `json:"id"` Name string `json:"name"` Age int `json:"age"` Token string `json:"token"` LastLoginTime string `json:"last_login_time"` CreateTime string `json:"create_time"` }
func (d *DemoApiController) Get(ctx *gin.Context) { ctx.JSON(200, map[string]interface{}{ "token": ctx.Request.Header.Get("x-token"), "name": ctx.Request.URL.Query().Get("name"), "age": ctx.Request.URL.Query().Get("age"), }) }
|
2.POST接口
type DemoRequest struct { XToken string `header:"X-Token" json:"XToken,omitempty"` Name string `json:"name" form:"name" example:"张三" ` Age int `json:"age" form:"age" example:"18"` }
func (d *DemoApiController) Post(ctx *gin.Context) { var param apitype.DemoRequest err := ctx.ShouldBindBodyWith(¶m, binding.JSON) if err != nil { ginutil.FailMsg(ctx, err.Error()) return } ctx.JSON(200, map[string]interface{}{ "token": ctx.Request.Header.Get("x-token"), "param": param, }) }
|
3. 文档注释说明
注释 |
描述 |
@Summary |
描述接口的具体作用 |
@Tags |
API 所属的模块列表,多个以逗号分隔。 |
@Accept |
API 可以使用的MIME 类型列表。 请注意,Accept 仅影响具有请求正文的操作,例如 POST、PUT 和 PATCH 。 值必须如“Mime类型”中所述。 |
@Produce |
API 可以生成的MIME 类型的列表。值必须如“Mime类型”中所述。 |
@Param |
指定参数信息;格式: @Param 参数名 参数类型 数据类型 必填 字段描述 示例:example("x") |
@success |
描述API 响应成功时,返回的数据结构示例 |
@Router |
指定API 访问路径,要和真实一致 |
4.更多使用
更多使用,可参见文档: https://github.com/swaggo/swag/blob/937c239a8ebd19a375d815fc6ca0fd54c63b9551/README_zh-CN.md
3.5 运行服务
1. 访问SwaggerUI
访问: http://0.0.0.0:8800/swagger/index.html
![](/img/loading.gif)