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

作者 | luorAx

提到 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 格式的文件，最外层节点中主要有以下字段：

httphttpswswss

Nirvana 中的配置

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

8081
nirvana init

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

versions.rules

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

Descriptor.PathDescriptor.ChildrenDescriptor.ConsumesDescriptor.ProducesDescriptor.TagsDescriptor.DefinitionsDefinition.MethodDefinition.ConsumesDefinition.ProducesDescriptorDefinition.TagsDescriptor.TagsDefinition.ParametersParameter.SourceParameter.NameParameter.DefaultParameter.DescriptionDefinition.ResultsDefinition.SummaryDefinition.DescriptionDefinition.ExamplesDefinition.Function

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

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