如何将 openAPI/Swagger 文件拆分为多个有效的子文件？

Question

我们的服务实现了不同级别的访问，并且我们在内部使用一个 openAPI YAML 文件。

出于外部文档的目的，我们希望创建多个 openAPI 文件，这些文件本身有效（自我维持），但仅具有全局文件的部分集，例如基于路径或标签。

（相同的路径可以在不同的分割文件中使用，但我认为这不是问题。）

关于如何实现这一目标有什么想法吗？有一些工具可以实现吗？

Answer 1

您可以在指向另一个资源的JSON 指针中使用有效的 URI 。URI 可以是本地文件、Web 资源等的路径：

paths:
  /user/{id}:
    summary: Get a user
    parameters:
      - $ref: "./path/to/file#/user_id"

# And so on...

OpenAPI 规范中的保留键必须是唯一的，因此我认为如果没有一些可以克服该限制的第三方实用程序，您将无法创建独立的 OpenAPI 规范。

但是，您将能够创建跨多个文件定义的有效独立 JSON 对象，并在索引文档中引用它们。网上有很多文章提供了例子：