OpenAPIv3协议主要使用在规范路由中，阅读接口文档协议介绍之前，请先了解一下规范路由：路由注册-规范路由

一、OpenAPIv3

详细的OpenAPIv3协议介绍请参考：https://swagger.io/specification/

二、g.Meta元数据

接口的元数据信息可以通过为输入结构体 embedded 方式嵌入 g.Meta 结构，并通过 g.Meta 的属性标签方式来实现。

关于元数据组件的介绍，详情请参考章节：元数据-gmeta 

三、常用协议标签

输入输出结构体中的属性的标签完整支持OpenAPIv3协议，因此只要增加了对应的协议标签，那么生成的OpenAPIv3接口信息中将会自动包含该属性。

大部分的标签属性已经被Server组件自动生成，开发者需要手动设置的标签不多。常见的标签包括：

常见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/

四、扩展OpenAPIv3信息

核心的接口信息已经自动生成，如果开发者想要更进一步完善接口信息，可以通过s.GetOpenApi()接口获取到OpenAPIv3的结构体对象，并手动填充对应的属性内容即可。我们来看一个示例，在该示例中，我们将接口中的标签进行了自定义的排序，并且增加了对每个标签的详细描述：

我们可以发现通过通用的OpenAPIv3对象我们可以自定义修改其内容，并且根据它生成其他各种自定义类型的接口文档。

Content Menu

  • No labels

16 Comments

  1. 我是小方我有点慌

    swagger页面在2.0.6版本只能本地访问，这个要怎么设置

  2. 我是小方我有点慌

    郭强 

  3. Eacher

    用配置文件设置的接口文档页面 请求的JS 不能用 https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js  

  4. 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 应该怎么写参数， 还是没有实现这部分？

    1. 仇小超

      请问解决了吗？

  5. Avocado

    如何定义多个 responses 

    目前按照文档定义都是生成 200 状态码的 response，如果想自定义 403，401，500 等状态码，对应 openapiv3 里面的 paths.response.xxx ，如何定义呢？

  6. Raymond

    请问能自定义API的排列顺序吗？现在看起来顺序是按path生成的

  7. 吕下阿蒙

    method方式如何同时支持get和post？ 找了半天也没找到例子，有谁知道吗

    1. 18lkdev

      应该不定义method就可以了吧你试试

      1. fangyu

        不定义也不行

  8. 大辉哥

    dc和sm对于struct类型的生成swagger不起作用！

  9. jack

    type LoginReq struct {
       AppId    string     `json:"app_id"   in:"header"   v:"required|length:5,32#应用ID不能为空|应用ID长度无效"  dc:"应用ID"`
       Nonce    string     `json:"nonce"   in:"header"   v:"required|length:5,32#1公共参数不能为空|公共参数长度无效"   dc:"随机数"`
       DateTime gtime.Time `json:"date_time"   in:"header"   v:"required|datetime#2公共参数不能为空|公共参数长度无效"   dc:"请求时间"`
       TimeZone string     `json:"time_zone"   in:"header"   v:"required|length:1,10#3公共参数不能为空|公共参数长度无效"  d:"PRC"   dc:"请求时区"`
       Sign     string     `json:"sign"   in:"header"   v:"required|size:32#4公共参数不能为空|公共参数长度无效"   dc:"签名"`
    }
    使用 PostMan header 提交 app_id 参数 提示 应用ID不能为空

    1. 糖水不加糖

      功能暂未实现,暂时在控制器内手动绑定并校验

      1. jack

        后续会支持吗？

  10. chamhaw

    group.PUT("/user", controller.User)

    手动注册路由，如果添加到swagger中去呢？

  11. HeNian

    openapi := s.GetOpenApi()
    openapi.Config.CommonResponse = ghttp.DefaultHandlerResponse{}
    openapi.Config.CommonResponseDataField = `Data`

    通过这个设置，可以将文档的返回结果与实际结果对应。
    但是 CommonResponseDataField 设置的字段只关联了类容没有关联 xxxRes 这个类型
    最终 data 的类型直接是Object 导致部分UI无法正常展开接口文档的结构。

    郭强