一、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

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

  5. Avocado

    如何定义多个 responses 

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

  6. Raymond

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

  7. HeNian

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

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