go开发web服务器 GoFrame WEB服务开发-接口文档

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

一、OpenAPIv3

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

二、g.Meta元数据

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

三、常用协议标签

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

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

四、扩展OpenAPIv3信息

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

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

五、常见问题

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

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