基于golang的swagger
Swagger 相关的工具集会根据 OpenAPI 规范去生成各式各类的与接口相关联的内容,常见的流程是编写注解 =》调用生成库-》生成标准描述文件 =》生成/导入到对应的 Swagger 工具。
github: swaggo/swag
一般步骤:
1.按照swagger要求给接口代码添加声明式注释(https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html)
整体api说明:
annotation | description | example |
---|---|---|
title | Required. The title of the application. | // @title Swagger Example API |
version | Required. Provides the version of the application API. | // @version 1.0 |
description | A short description of the application. | // @description This is a sample server celler server. |
termsOfService | The Terms of Service for the API. | // @termsOfService http://swagger.io/terms/ |
contact.name | The contact information for the exposed API. | // @contact.name API Support |
contact.url | The URL pointing to the contact information. MUST be in the format of a URL. | // @contact.url http://www.swagger.io/support |
contact.email | The email address of the contact person/organization. MUST be in the format of an email address. | // @contact.email support@swagger.io |
license.name | Required. The license name used for the API. | // @license.name Apache 2.0 |
license.url | A URL to the license used for the API. MUST be in the format of a URL. | // @license.url http://www.apache.org/licenses/LICENSE-2.0.html |
host | The host (name or ip) serving the API. | // @host localhost:8080 |
BasePath | The base path on which the API is served. | // @BasePath /api/v1 |
Security
annotation | description | parameters | example |
---|---|---|---|
securitydefinitions.basic | Basic auth. | // @securityDefinitions.basic BasicAuth | |
securitydefinitions.apikey | API key auth. | in, name | // @securityDefinitions.apikey ApiKeyAuth |
securitydefinitions.oauth2.application | OAuth2 application auth. | tokenUrl, scope | // @securitydefinitions.oauth2.application OAuth2Application |
securitydefinitions.oauth2.implicit | OAuth2 implicit auth. | authorizationUrl, scope | // @securitydefinitions.oauth2.implicit OAuth2Implicit |
securitydefinitions.oauth2.password | OAuth2 password auth. | tokenUrl, scope | // @securitydefinitions.oauth2.password OAuth2Password |
securitydefinitions.oauth2.accessCode | OAuth2 access code auth. | tokenUrl, authorizationUrl, scope | // @securitydefinitions.oauth2.accessCode OAuth2AccessCode |
parameters annotation | example |
---|---|
in | // @in header |
name | // @name Authorization |
tokenUrl | // @tokenUrl https://example.com/oauth/token |
authorizationurl | // @authorizationurl https://example.com/oauth/authorize |
scope.hoge | // @scope.write Grants write access |
Example
具体的API说明:
annotation | description |
---|---|
description | A verbose explanation of the operation behavior. |
id | A unique string used to identify the operation. Must be unique among all API operations. |
tags | A list of tags to each API operation that separated by commas. |
summary | A short summary of what the operation does. |
accept | A list of MIME types the APIs can consume. Value MUST be as described under Mime Types. |
produce | A list of MIME types the APIs can produce. Value MUST be as described under Mime Types. |
param | Parameters that separated by spaces. param name ,param type ,data type ,is mandatory? ,comment attribute(optional) |
security | Security to each API operation. |
success | Success response that separated by spaces. return code ,{param type} ,data type ,comment |
failure | Failure response that separated by spaces. return code ,{param type} ,data type ,comment |
router | Failure response that separated by spaces. path ,[httpMethod] |
Example
Limitation
- Not supported for cross-package models. Only search in project root folder. See #39
Mime Types
Mime Type | annotation |
---|---|
application/json | application/json, json |
text/xml | text/xml, xml |
text/plain | text/plain, plain |
html | text/html, html |
multipart/form-data | multipart/form-data, mpfd |
application/x-www-form-urlencoded | application/x-www-form-urlencoded, x-www-form-urlencoded |
application/vnd.api+json | application/vnd.api+json, json-api |
application/x-json-stream | application/x-json-stream, json-stream |
application/octet-stream | application/octet-stream, octet-stream |
image/png | image/png, png |
image/jpeg | image/jpeg, jpeg |
image/gif | image/gif, gif |
Security
General API info.
// @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
Each API operation.
// @Security ApiKeyAuth
Make it AND condition
// @Security ApiKeyAuth
// @Security OAuth2Application[write, admin]
Param Type
- object (struct)
- string (string)
- integer (int, uint, uint32, uint64)
- number (float32)
- boolean (bool)
- array
Data Type
- string (string)
- integer (int, uint, uint32, uint64)
- number (float32)
- boolean (bool)
- user defined struct
Attribute
// @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" mininum(1) maxinum(10)
// @Param default query string false "string default" default(A)
Available
Field Name | Type | Description |
---|---|---|
default | * | Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined type for this parameter. |
maximum | number |
See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. |
minimum | number |
See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. |
maxLength | integer |
See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1. |
minLength | integer |
See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2. |
enums | [*] | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1. |
Future
Field Name | Type | Description |
---|---|---|
format | string |
The extending format for the previously mentioned type . See Data Type Formats for further details. |
multipleOf | number |
See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. |
pattern | string |
See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. |
maxItems | integer |
See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. |
minItems | integer |
See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. |
uniqueItems | boolean |
See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. |
collectionFormat | string |
Determines the format of the array if type array is used. Possible values are:
csv . |
TIPS
User defined structure with an array type
// @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"`
}
Use multiple path params
/// ...
// @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]
Example value of struct
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"`
}
2.使用swag工具扫描代码自动生成api接口文档数据(docs/)
3.使用gin-swagger渲染在线接口文档页面
[安装]
$ go get -u github.com/swaggo/swag/cmd/swag $ go get -u github.com/swaggo/gin-swagger $ go get -u github.com/swaggo/files $ go get -u github.com/alecthomas/template
验证是否安装成功
swag -v swag version v1.8.1
[添加注释]
1.在main主入口文件添加项目相关介绍信息
package main // @title 这里写标题 // @version 1.0 // @description 这里写描述信息 // @termsOfService http://swagger.io/terms/ // @contact.name 这里写联系人信息 // @contact.url http://www.swagger.io/support // @contact.email support@swagger.io // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @host 这里写接口服务的host // @BasePath 这里写base path func main() { r := gin.New() // liwenzhou.com ... r.Run() }
2.在代码中处理请求的接口函数添加注释
// GetPostListHandler2 升级版帖子列表接口 // @Summary 升级版帖子列表接口 // @Description 可按社区按时间或分数排序查询帖子列表接口 // @Tags 帖子相关接口 // @Accept application/json // @Produce application/json // @Param Authorization header string false "Bearer 用户令牌" // @Param object query models.ParamPostList false "查询参数" // @Security ApiKeyAuth // @Success 200 {object} _ResponsePostList // @Router /posts2 [get] func GetPostListHandler2(c *gin.Context) { // GET请求参数(query string):/api/v1/posts2?page=1&size=10&order=time // 初始化结构体时指定初始参数 p := &models.ParamPostList{ Page: 1, Size: 10, Order: models.OrderTime, } if err := c.ShouldBindQuery(p); err != nil { zap.L().Error("GetPostListHandler2 with invalid params", zap.Error(err)) ResponseError(c, CodeInvalidParam) return } data, err := logic.GetPostListNew(p) // 获取数据 if err != nil { zap.L().Error("logic.GetPostList() failed", zap.Error(err)) ResponseError(c, CodeServerBusy) return } ResponseSuccess(c, data) // 返回响应 }
// bluebell/models/params.go // ParamPostList 获取帖子列表query string参数 type ParamPostList struct { CommunityID int64 `json:"community_id" form:"community_id"` // 可以为空 Page int64 `json:"page" form:"page" example:"1"` // 页码 Size int64 `json:"size" form:"size" example:"10"` // 每页数据量 Order string `json:"order" form:"order" example:"score"` // 排序依据 }
1 2 3 4 5 6 7 8 | // bluebell/controller/docs_models.go // _ResponsePostList 帖子列表接口响应数据 type _ResponsePostList struct { Code ResCode `json: "code" ` // 业务响应状态码 Message string `json: "message" ` // 提示信息 Data []*models.ApiPostDetail `json: "data" ` // 数据 } |
注解部分说明:
注解 描述 @Summary 摘要 @Produce API 可以产生的 MIME 类型的列表,MIME 类型你可以简单的理解为响应类型,例如:json、xml、html 等等 @Param 参数格式,从左到右分别为:参数名、入参类型、数据类型、是否必填、注释 @Success 响应成功,从左到右分别为:状态码、参数类型、数据类型、注释 @Failure 响应失败,从左到右分别为:状态码、参数类型、数据类型、注释 @Router 路由,从左到右分别为:路由地址,HTTP 方法 2.4.4.1 API 我们切换到项目目录下的 internal/routers/api/v1 目录,打开 tag.go 文件,写入如下注解:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | // @Summary 获取多个标签 // @Produce json // @Param name query string false "标签名称" maxlength(100) // @Param state query int false "状态" Enums(0, 1) default(1) // @Param page query int false "页码" // @Param page_size query int false "每页数量" // @Success 200 {object} model.Tag "成功" // @Failure 400 {object} errcode.Error "请求错误" // @Failure 500 {object} errcode.Error "内部错误" // @Router /api/v1/tags [get] func (t Tag) List(c *gin.Context) {} // @Summary 新增标签 // @Produce json // @Param name body string true "标签名称" minlength(3) maxlength(100) // @Param state body int false "状态" Enums(0, 1) default(1) // @Param created_by body string true "创建者" minlength(3) maxlength(100) // @Success 200 {object} model.Tag "成功" // @Failure 400 {object} errcode.Error "请求错误" // @Failure 500 {object} errcode.Error "内部错误" // @Router /api/v1/tags [post] func (t Tag) Create(c *gin.Context) {} // @Summary 更新标签 // @Produce json // @Param id path int true "标签 ID" // @Param name body string false "标签名称" minlength(3) maxlength(100) // @Param state body int false "状态" Enums(0, 1) default(1) // @Param modified_by body string true "修改者" minlength(3) maxlength(100) // @Success 200 {array} model.Tag "成功" // @Failure 400 {object} errcode.Error "请求错误" // @Failure 500 {object} errcode.Error "内部错误" // @Router /api/v1/tags/{id} [put] func (t Tag) Update(c *gin.Context) {} // @Summary 删除标签 // @Produce json // @Param id path int true "标签 ID" // @Success 200 {string} string "成功" // @Failure 400 {object} errcode.Error "请求错误" // @Failure 500 {object} errcode.Error "内部错误" // @Router /api/v1/tags/{id} [delete] func (t Tag) Delete(c *gin.Context) {} |
[生成接口文档数据]
swag init
--generallinfo value 指定go项目入口文件, 默认是main.go
--swagger value 配置输出的文件的目录 默认 ./docs/swagger
# 指定入口文件与输出路径
swag init -g cmd/app/main.go -o ./docs
./docs ├── docs.go ├── swagger.json └── swagger.yaml
[渲染文档]
import ( // liwenzhou.com ... _ "bluebell/docs" // 千万不要忘了导入把你上一步生成的docs gs "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" "github.com/gin-gonic/gin" ) 注册路由: r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) 把你的项目程序运行起来,打开浏览器访问 http://localhost:8080/swagger/index.html 就能看到Swagger 2.0 Api文档了。 gin-swagger 同时还提供了 DisablingWrapHandler 函数,方便我们通过设置某些环境变量来禁用Swagger。例如: r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE")) 此时如果将环境变量 NAME_OF_ENV_VARIABLE设置为任意值,则 /swagger/*any 将返回404响应,就像未指定路由时一样。
常见错误:
1.
Failed to load API definition
原因:
_ "bluebell/docs" // 千万不要忘了导入把你上一步生成的docs 缺少这个初始化并注册操作
问题见:https://github.com/swaggo/swag/issues/830
参考文档:
- https://www.cnblogs.com/niuben/p/15634136.html
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· DeepSeek “源神”启动!「GitHub 热点速览」
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 我与微信审核的“相爱相杀”看个人小程序副业
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· spring官宣接入deepseek,真的太香了~
2019-05-29 微信之语音存储
2018-05-29 VMware虚拟机中常见的问题汇总
2018-05-29 Windows10下安装VMware虚拟机并搭建CentOS系统环境