开源 Golang API 框架 Nirvana 的 OpenAPI 实践

3 年前

才云Caicloud

点燃数据与计算的价值

Nirvana 是才云实现并开源的 Golang API 框架，它借鉴了 Kubernetes 声明式 API 的设计，巧妙规避了框架对 API 的侵入，把 API 从对框架的依赖中彻底解放出来，专为提高生产力和可用性设计。本文探讨了基于 Nirvana 的 openAPI 实践，旨在帮助开发者从繁重的文档写作任务中解脱出来。

发布 | 才云 Caicloud

作者 | luorAx

项目 | https:// github.com/caicloud/nir vana

提到 OpenAPI，就不得不提 RESTful API。简单来说，RESTful API 是指导设计 Web 应用 API 的规范，而 OpenAPI 是指导编写 Web 应用 API 文档的规范，是对 RESTful API 实现细节的描述。服务使用能够根据符合 OpenAPI 规范的应用服务API 文档理解调用服务的方式，并通过工具快速生成客户端代码以及交互式的 UI 界面。

目前 OpenAPI 只支持 HTTP 协议。

OpenAPI 规范目前主要的版本有 2.0 以及 3.0。其中，OpenAPI 2.0 是从 Swagger 2.0 重命名而来的，使用者众多。OpenAPI 3.0 对规范进行了扩充，增加了 Multiple Servers、Components 等新字段。

OpenAPI 文件结构

符合 OpenAPI 2.0 规范的文件载体可以是 JSON 或 YAML 格式的文件，最外层节点中主要有以下字段：

swagger ：OpenAPI 规范版本，必须为 2.0
info ：API 文档的描述、版本等元数据信息
host ：提供 API 服务的主机或者 IP
basePath ：API 的基础路径
schemes ：API 的传输协议，只能为 http 、 https 、 ws 、 wss
paths ：API 支持的路径以及每个路径下支持的操作
definitions ：可以在文档中被引用的对象
securityDefinitions ：API 使用的安全验证方案

Nirvana 中的配置

Nirvana 是才云开源的 Golang API 框架 ，通过声明式 API 定义，让 API 按照规范编写，同时能够根据声明式 API 自动生成符合 OpenAPI 2.0 规范的文档（《才云 Caicloud 开源 Nirvana：让 API 从对框架的依赖中涅槃重生》）。开发者使用 Nirvana 自动生成可交互式文档的步骤十分简单：

运行以上命令后，openapi-example/doc 目录下会有一份静态 API 文档，我们访问本地的 8081 端口就可以在浏览器中查看可交互式的文档。

Nirvana 主要通过两部分配置来自动生成文档，第一部分是使用 nirvana init 初始化项目时生成 nirvana.yaml 配置文件，第二部分是项目中的 Descriptor、Definition 所在的包路径。

nirvana.yaml 中的 project、description、contacts、versions 字段被用于生成 OpenAPI 的 info 信息，schemes、hosts 则与 OpenAPI 中的 schemes、host 相对应。

需要注意的是， nirvana.yaml 中支持配置多个 host，但是在生成 API 文档时只会使用第一个 host 。 versions.rules 字段可用于匹配不同 API 路径，满足匹配规则的路径会被添加到对应版本的 API 文档中，可以在配置文件的多个版本中通过 versions.rules 包含一些共用的 API，比如健康检查。

Nirvana 通过 Descriptor、Definition 两种结构体声明 API 路径以及路径下的操作：

Descriptor.Path 、 Descriptor.Children 拼接成完整的 API 路径
Descriptor.Consumes 、 Descriptor.Produces 定义了路径下的默认请求数据与响应数据类型
Descriptor.Tags 是路径的默认标签，会重写父级标签
Descriptor.Definitions 是对路径下支持的操作集合
Definition.Method 字段定义 HTTP 的请求方法
Definition.Consumes 、 Definition.Produces 会重写 Descriptor 中定义的 Consumes 和 Produces
Definition.Tags 会重写 Descriptor.Tags
Definition.Parameters 定义了 API 请求参数
Parameter.Source 可以来自 http header、http url path、http request body（包含表单以及文件类型）
Parameter.Name 配置了请求参数在请求头以及表单中的键名
Parameter.Default 配置参数的默认值，配置该值时，在生成文档的时候会将该参数标记为 Required
Parameter.Description 设置参数的描述信息
Definition.Results 目前在自动生成文档时只支持配置在响应体中的返回值，Nirvana 会自动填充该 HTTP 方法所对应的响应码、返回值类型以及响应对应的返回数据
Definition.Summary 用于设置文档的概要信息，同时在自动生成客户端代码时设置方法名
Definition.Description 设置该操作的描述信息
Definition.Examples 设置响应消息的示例，目前只支持 JSON 格式的值
Definition.Function 是 Definition 对应的业务逻辑方法，如果 Definition 中的 Summary 未设置时，会用 Function 名填充；Description 未设置时，会用 Function 上方的注释填充

通过编写 nirvana.yaml 文件以及代码中的 Definition 和 Descriptor，开发者在编码的同时就能完成 API 文档，从而释放编写文档的繁重任务。

Nirvana 围绕开发者亲历的种种痛点设计，致力于成为让业务无感知的框架。我们真诚欢迎更多开发者的加入，一起构建 Nirvana，一起建设 Golang 社区，让这场涅槃（nirvana）更加炫目！如果您有兴趣为 Nirvana 贡献，请查看： https:// github.com/caicloud/nir vana/blob/master/CONTRIBUTING.md

发布于 2020-07-28 10:10