Question

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

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

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

Answer 1

对于那些不确定如何实现的人，我就是这样做的：

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

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

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

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

要浏览yaml文件，我使用了以下python库：ruamel

因此，我一直在递归地浏览文件以查找OpenApi操作，该操作的标签称为“ Private”或描述标签包含字符序列“ Private ”的属性

Answer 2

为多个使用上下文实例化同一OpenAPI文件是常见的需求。经典的解决方案是复制粘贴文件，但是在可维护性方面并不好！因为我有相同的需求，所以我编写了自己的工具“ OpenAPI Dev Tool”（请参阅github）。

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

例如，您可以定义一个配置文件：

"searchResults": [
    {
        "startTime": 1604466366253,
        "parameter": {
            "name": "CntIOParts",
            "value": 0,
            "datatype": "int"
        }
    },
    {
        "startTime": 1604478998001,
        "parameter": {
            "name": "CntIOParts",
            "value": 0,
            "datatype": "int"
        }
    }]

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

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

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

最后，将在同一个YAML文件中生成2个规范，但要针对这2个上下文：）

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

2 个答案: