OpenAPI 很难

“这能有多难？”

原标题：OpenAPI 很难
文章来源：AI前线
内容字数：5533字

OpenAPI：比你想象的难得多

本文讲述了作者quobix构建一个完全理解OpenAPI的引擎、框架和平台的经历，以及过程中遇到的巨大挑战。作者最初低估了任务的难度，认为仅仅是解析YAML或JSON格式的数据，事实却远非如此。

1. OpenAPI的复杂性

OpenAPI并非简单的语言，而是由多种其他语言（如YAML、JSON、JSON Schema）组成的复杂系统。YAML支持锚点、别名和有序列表，而JSON则不支持，这导致了兼容性问题。JSON Schema本身就是一个复杂的标准，JSON指针的处理也增加了难度。这种多重语言的组合使得OpenAPI的解析和处理变得异常棘手。

2. 解析与编译的挑战

简单的JSON解析在遇到重复数据和引用（JSON指针）时就会失效。工程师需要构建查找表或哈希表来索引和拼接引用，处理循环引用造成的无限循环或堆栈溢出问题。作者指出，这实际上需要编写解释器和编译器，而非简单的解析器，这大大增加了任务的复杂性。许多工程师最终放弃自行开发，转而使用现成的库，但这些库往往功能不完善。

3. Rolodex系统的构建

为了解决引用和文件管理问题，作者构建了“Rolodex”系统，这是一个复杂的索引系统，用于在庞大的文件网络中查找和管理指针。这个系统的构建耗费了大量时间和精力，最终效果却并不如预期理想，这体现了在处理复杂系统时，过度设计可能带来的问题。

4. OpenAPI Doctor的强大功能

作者展示了其构建的OpenAPI Doctor工具，该工具能够高效地处理和可视化OpenAPI规范，包括处理大量的引用和文件。用户可以轻松跳转到文档中的不同位置，查看和诊断引用，探索复杂的规范结构，这得益于底层Rolodex系统的支持。

5. 处理大型规范的挑战

作者用DigitalOcean OpenAPI规范（1600多个文件，数十万个引用）来测试OpenAPI Doctor，证明了该工具能够处理超大型规范，而大多数其他工具则会崩溃或失败。这突显了OpenAPI Doctor在处理复杂、大型OpenAPI规范方面的优势。

6. 结论

本文通过作者的亲身经历，揭示了构建一个完全理解OpenAPI的引擎的巨大挑战。这不仅需要深入理解多种语言和规范，还需要处理复杂的引用和循环引用问题。OpenAPI Doctor的成功，证明了通过精心设计和强大的底层架构，可以有效地应对这些挑战。

联系作者

文章来源：AI前线
作者微信：
作者简介：面向AI爱好者、开发者和科学家，提供大模型最新资讯、AI技术分享干货、一线业界实践案例，助你全面拥抱AIGC。