从 yaml 文件创建公共和私有 Open API 文档

Question

我有一个 OpenAPI 文档来描述一些端点。其中一些端点应是公共的（对最终用户可见），其他端点应是私有的（仅对开发团队可见）。

我想知道是否有办法只创建 1 个包含所有 api 方法的 yaml 文件并生成 2 个文档页面（1 个用于公共端点，其他用于私有端点）。是否有一个标志或配置允许我区分端点类型并使其可见或隐藏？

我还需要根据请求级别执行此操作。在某些端点中，请求正文具有一些“私有”属性（最终用户不应该知道）。假设第一个语句是正确的（有一种方法可以从单个 YAML 文件创建 2 个 api 文档），那么在应用公共别名文档时是否可以隐藏一些请求模型属性？

Answer 1

对于那些怀疑如何实现这一点的人，我就是这样做的：

• 我创建了一组对 OpenApi 透明的私有关键字（它们是通用字符串）
• 我还创建了一个 Python 脚本，用于导航 yaml 文件，每次找到这些私有关键字之一时，它都会删除它所包含的 yaml 节点。

问：我如何设法为端点做到这一点？答：我在“标签”部分创建了一个名为“私有”的标签，所有私有端点都必须引用它。这就是我删除专用端点的方法。

问：我如何设法对属性做到这一点？答：在属性（或我想要设为私有的任何元素）“描述”标签中，我添加关键字“ Private ”。因此，如果我的脚本在描述中找到该字符串，则该元素将被删除。

当然，对于私有 OpenApi yaml 文件，我创建的这些用于生成公共版本的标签仍然存在。但由于它们只是字符串，所以这没什么大不了的。

为了通过 yaml 文件进行导航，我使用了以下 python 库：ruamel

因此，我不断递归地浏览文件，搜索标签称为“Private”的 OpenApi 操作或描述标签包含字符序列“ Private ”的属性