时间戳

首页 > 解决方案 > 从 yaml 文件创建公共和私有 Open API 文档

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

问题描述

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

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

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

标签： yamlopenapi

解决方案

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

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

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

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

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

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

所以我一直在文件中递归地浏览标签称为“私有”的 OpenApi 操作或描述标签包含字符序列“私有”的属性

推荐阅读