swagger - 设置多个 swagger API 文件

Question

我正在做一个项目，我们重写现有应用程序的接口，将所有内容移植到 swagger/openAPI。

现在，每个特性都有自己的 yml 文件，这是一个独立的规范。但也有一些缺点：

• yml 文件中的重复内容（例如，可以跨文件共享的模型）
• 重复的程序代码（从那些 yml 文件生成）。
• 使用工具时必须单独处理每个 yml 文件。

理想情况下，我们希望每个服务都有一个单独的文件夹，该特定服务的模型和服务描述靠近在一起，但与其他服务分开。当然也有共享模型，然后我们想要在不同的文件夹中（例如“/shared-models”）。最后，我们希望所有这些文件都包含在1 个主 yml 根文件中。

因此，我们一直在研究使用$ref属性拆分/导入文件。但是想出一个完整的文件和文件夹结构是很棘手的，因为规范似乎允许$ref在某些地方使用，但不是所有地方。您不能以任何您喜欢的方式拆分和构造文件。所以，我们可能需要某种权衡。

我特别想知道其他公司如何进行此设置。（例如，使用企业级结构的 swagger 文件的设置示例会非常好。）我们希望尽可能根据标准或流行约定保持简单。

（为了清楚起见：我的问题不是：“如何使用 $ref”）

标签： swaggeropenapi