GoFrame框架支持全自动化的接口文档生成,保障代码与接口文档同步维护,自动生成的接口文档采用的是标准的OpenAPIv3协议。在介绍OpenAPIv3协议之前,建议您先阅读了解框架的规范路由特性:路由注册-规范路由

接口文档 - 图1

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

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

接口文档 - 图2

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

五、常见问题

1、如何实现文件上传的接口定义?

  • 参数接收的数据类型使用*ghttp.UploadFile
  • 如果需要接口文档也支持文件类型,那么参数的标签中设置typefile类型

接口文档 - 图3

接口文档 - 图4