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对象我们可以自定义修改其内容，并且根据它生成其他各种自定义类型的接口文档。

Content Menu

  • No labels