- Created by 郭强, last modified on Mar 06, 2024
OpenAPIv3
协议主要使用在规范路由中,阅读接口文档协议介绍之前,请先了解一下规范路由:路由注册-规范路由
一、OpenAPIv3
详细的OpenAPIv3
协议介绍请参考:https://swagger.io/specification/
二、g.Meta
元数据
接口的元数据信息可以通过为输入结构体 embedded
方式嵌入 g.Meta
结构,并通过 g.Meta
的属性标签方式来实现。
关于元数据组件的介绍,详情请参考章节:元数据-gmeta
三、常用协议标签
输入输出结构体中的属性的标签完整支持OpenAPIv3
协议,因此只要增加了对应的协议标签,那么生成的OpenAPIv3
接口信息中将会自动包含该属性。
大部分的标签属性已经被Server
组件自动生成,开发者需要手动设置的标签不多。
1、基础标签
常见的基础标签包括:
常见OpenAPIv3标签 | 说明 | 备注 |
---|---|---|
path | 结合注册时的前缀共同构成接口URI路径 | 用于g.Meta 标识接口元数据 |
tags | 接口所属的标签,用于接口分类 | 用于g.Meta 标识接口元数据 |
method | 接口的请求方式:GET/PUT/POST/DELETE...(不区分大小写) | 用于g.Meta 标识接口元数据 |
deprecated | 标记该接口废弃 | 用于g.Meta 标识接口元数据 |
summary | 接口/参数概要描述 | 缩写sm |
description | 接口/参数详细描述 | 缩写dc |
in | 参数的提交方式 | header/path/query/cookie |
default | 参数的默认值 | 缩写d |
mime | 接口的MIME 类型,例如multipart/form-data 一般是全局设置,默认为application/json 。 | 用于g.Meta 标识接口元数据 |
type | 参数的类型,一般不需要设置,特殊参数需要手动设置,例如file | 仅用于参数属性 |
更多标签请参考标准的OpenAPIv3
协议:https://swagger.io/specification/
2、扩展标签
在OpenAPI
规范里面,所有名称以x-
开头的标签是开发者可自定义的扩展标签。扩展标签可以在任意的接口、属性中以Golang struct tag
的形式定义,在接口文档生成时,将会作为独立的字段返回。例如:
package main import ( "context" "github.com/gogf/gf/v2/errors/gcode" "github.com/gogf/gf/v2/errors/gerror" "github.com/gogf/gf/v2/frame/g" "github.com/gogf/gf/v2/net/ghttp" ) type GetListReq struct { g.Meta `path:"/user" tags:"User" method:"get" x-group:"User/Info" summary:"Get user list with basic info."` Page int `dc:"Page number" d:"1" x-sort:"1"` Size int `dc:"Size for per page." d:"10" x-sort:"2"` } type GetListRes struct{} type Controller struct{} func (c *Controller) GetList(ctx context.Context, req *GetListReq) (res *GetListRes, err error) { return nil, gerror.NewCode(gcode.CodeNotImplemented) } func main() { s := g.Server() s.Group("/", func(group *ghttp.RouterGroup) { group.Bind(new(Controller)) }) s.SetOpenApiPath("/api.json") s.SetSwaggerPath("/swagger") s.SetPort(8199) s.Run() }
执行后,访问地址 http://127.0.0.1:8199/swagger 可以查看swagger ui
,访问 http://127.0.0.1:8199/api.json 可以查看对应的OpenAPIv3
接口文档。其中生成的OpenAPIv3
接口文档如下:
{ "openapi": "3.0.0", "components": { "schemas": { "main.GetListReq": { "properties": { "Page": { "default": 1, "description": "Page number", "format": "int", "properties": {}, "type": "integer", "x-sort": "1" }, "Size": { "default": 10, "description": "Size for per page.", "format": "int", "properties": {}, "type": "integer", "x-sort": "2" } }, "type": "object", "x-group": "User/Info" }, "main.GetListRes": { "properties": {}, "type": "object" } } }, "info": { "title": "", "version": "" }, "paths": { "/user": { "get": { "parameters": [ { "description": "Page number", "in": "query", "name": "Page", "schema": { "default": 1, "description": "Page number", "format": "int", "properties": {}, "type": "integer", "x-sort": "1" }, "x-sort": "1" }, { "description": "Size for per page.", "in": "query", "name": "Size", "schema": { "default": 10, "description": "Size for per page.", "format": "int", "properties": {}, "type": "integer", "x-sort": "2" }, "x-sort": "2" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/main.GetListRes" } } }, "description": "" } }, "summary": "Get user list with basic info.", "tags": [ "User" ], "x-group": "User/Info" }, "x-group": "User/Info" } } }
可以看到,扩展标签已经生成到了接口文档中。
四、扩展OpenAPIv3
信息
核心的接口信息已经自动生成,如果开发者想要更进一步完善接口信息,可以通过s.GetOpenApi()
接口获取到OpenAPIv3
的结构体对象,并手动填充对应的属性内容即可。我们来看一个示例,在该示例中,我们设计每个接口外层公共的数据结构:
我们可以发现通过通用的OpenAPIv3
对象我们可以自定义修改其内容,并且根据它生成其他各种自定义类型的接口文档。
- No labels
38 Comments
我是小方我有点慌
swagger页面在2.0.6版本只能本地访问,这个要怎么设置
dongtao
请问解决了吗?
我是小方我有点慌
郭强
Eacher
用配置文件设置的接口文档页面 请求的JS 不能用 https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js
beautiful
/store/inventory:
get:
tags:
- store
summary: Returns pet inventories by status
description: Returns a map of status codes to quantities
operationId: getInventory
responses:
200:
description: successful operation
content:
application/json:
schema:
type: object
additionalProperties:
type: integer
format: int32
security:
- api_key: []
像这种security 应该怎么写参数, 还是没有实现这部分?
仇小超
请问解决了吗?
kejj
Avocado
如何定义多个 responses
目前按照文档定义都是生成 200 状态码的 response,如果想自定义 403,401,500 等状态码,对应 openapiv3 里面的 paths.response.xxx ,如何定义呢?
Evans
嗨,请问解决了吗
Raymond
请问能自定义API的排列顺序吗?现在看起来顺序是按path生成的
吕下阿蒙
method方式如何同时支持get和post? 找了半天也没找到例子,有谁知道吗
18lkdev
应该不定义method就可以了吧你试试
陈鹏
你解决了吗?不定义就要报错
harbor
同问
糖水不加糖
新版本应该可以 method:"get,post"
郭强
吕下阿蒙 18lkdev 陈鹏 harbor 是的,最新版本是支持的了:规范路由-常见问题
大辉哥
dc和sm对于struct类型的生成swagger不起作用!
jack
糖水不加糖
功能暂未实现,暂时在控制器内手动绑定并校验
jack
后续会支持吗?
chamhaw
手动注册路由,如果添加到swagger中去呢?
HeNian
openapi := s.GetOpenApi()
openapi.Config.CommonResponse = ghttp.DefaultHandlerResponse{}
openapi.Config.CommonResponseDataField = `Data`
通过这个设置,可以将文档的返回结果与实际结果对应。
但是 CommonResponseDataField 设置的字段只关联了类容没有关联 xxxRes 这个类型
最终 data 的类型直接是Object 导致部分UI无法正常展开接口文档的结构。
郭强
overbeck.jack
目前的请求/响应结构体前缀路径使用的是 go.mod ,如:github.com-aaa-bbb.api.hello.v1.HelloReq ,如何自定义修改前缀 github.com-aaa-bbb ??? 郭强
因为在与第三方对接时,不希望把项目的完整地址展示出去,可能只需要把 github.com-aaa-bbb ==> aaa-bbb
shiqinfeng
默认生成的response的body定义只有自定义返回数据的格式, 请问怎么才能把默认的code,message和data,这3个字段也加到定义里面
郭强
可以参考
cgd
郭强
g.RequestFromCtx(ctx).GetClientIP()
wwmin
如何定义一个符合OpenAPIv3标准的上传文件接口tag, 目前
目前这种定义生成的json不是标准的OpenApiV3格式, 导致SwaggerUI 中Try It Out 不能识别到是文件, 无法直接在swagger中做测试
yud
g.Meta的tags里,加上format:"binary" 试试呢
wwmin
加上format:"binary"还是没有识别为file类型
wwmin
该问题已在2.6中解决
lfzxs
能不能指定某个字段不被解析为参数?如:
type tagsSearchReq struct {
g.Meta `path:"/list" tags:"标签管理" method:"get" summary:"列表"`
Name string `p:"name"`
Tenant string
}
中的Tenant 我不想做为参数给用户传,也不显示在openapi文档上。
breath
data能提取一个ref出来吗?我的场景是code-gen自动生成前端代码,由于没有确切类型和名字,全部生成为了xxxInLine名字的文件。
Aii
能单独隐藏某个路径吗?
JonnyJiang
通过swagger测试jwt的时候,发现请求体里的认证请求体不能被请求带上。
请问一下是我使用的方式有问题还是说目前swagger不支持这样
JonnyJiang
郭强
king
想要对此处的 UserBindPara 做一些案例说明,但是如果把 example写成json,在API UI上出来的example是字符串不是kv结构的object, 如果不写example 出来的就是object,但是key是随机的
因为这边的第三方接口返回的内容,根据供应商的不同 返回的结构也不同,没法写成struct
Y.Jie
可以设置全局header么?