从 yaml 文件创建 public 和私有打开 API 文档

Question

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

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

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

Answer 1

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

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

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

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

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

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

所以我一直在文件中递归导航，搜索标签称为 "Private" 的 OpenApi 操作或描述标签包含字符序列“Private 的属性“

Answer 2

为多个使用环境实例化同一个 OpenAPI 文件是一种常见的需要。经典的解决方案是 copy-paste 您的文件，但在可维护性方面不是很好！因为我有同样的需求，所以我自己写了一个工具“OpenAPI Dev Tool”（参见github）。

使用此工具，您可以只设计一个 API 并将其实例化用于多个上下文（例如私有/public），而无需重复任何行或文件（它使用 EJS 模板引擎）。

例如，您可以定义这样的配置文件：

{
"folder": "./specs", 
"specs": [           
    {
        "file": "/petstore.yaml",
        "context": {
          private: true
        }
    },
    {
        "file": "/petstore.yaml"
        "context": {
          private: false
        }
    }
]
}

其中指定了相同的 YAML 文件，但用于 2 个不同的上下文（public / 私有）。

并且在您的 petstore.yaml 中，您可以拥有：

openapi: 3.0.0
...

components:
<%if (public) { %>
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
<% } %>

...

<%if (public) { %>
security:
- basicAuth: []
<% } %>
...

最后，将从同一个 YAML 文件生成 2 个规范，但对于这 2 个上下文 :)

从 yaml 文件创建 public 和私有打开 API 文档

Creating public and private Open API documentation from yaml file

yaml

openapi