OpenApi Generator 在 YAML 文件规范中引用外部 POJO

Question

我正在使用OpenApi v3.3.4（以前称为Swagger CodeGen）maven 插件通过api.yml 文件生成我的rest 控制器，其中我描述了我想要公开的所有操作。

在我的用例中，我想公开一个方法 POST: handleNotification(@RequestBody SignatureNotification notification)，它的请求主体的类型是通过 /targer 文件夹中的另一个 maven-plugin 生成的。

实际上，我在 .yml 文件的 Componentspart 中定义了 SignatureNotification：

...
requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignatureNotification'
...

由 OpenApi 插件生成，然后我将其映射到已经存在且具有相同属性的 SignatureNotification。

我对这个解决方案不是很满意，所以我想知道是否有办法告诉 OpenApi Generator 使用外部对象作为参考？

Answer 1

如果我正确理解您的需求，您只想告诉生成器不要再次生成您现有的类。 如果以上正确，那么您可以像这样配置插件importMappings：

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>${openapi-generator-maven-plugin.version}</version>
  <configuration>
      ... excluded for simplicity
      <importMappings>
          <importMapping>SignatureNotification=path.to.your.SignatureNotification</importMapping>        
      </importMappings>
  </configuration>
</plugin>

使用此配置，openapi 生成器不会从 SignatureNotification 定义生成类，而是使用现有的。

Answer 2

理论：

根据 openapi 规范，$ref 也可以是对外部文件的引用。您可以阅读有关它的所有信息here。

现实：

话虽如此，我宁愿根本不使用它。恕我直言，openapi 规范过于正式/显式/臃肿，无法与外部文件引用一起使用。

相反，我更喜欢将内容拆分到单独的文件中不添加来自根 yml 文件的引用。

我的文件很小。一旦我想通过工具处理它们，我只需将所有内容重新合并在一起。编写脚本来合并它们实际上并不难。

• 我在 components\schemas 文件夹中创建单独的文件。每个文件包含一个或多个模型定义。我基本上可以将它们放在任何子文件夹中。 （将它们排列在子文件夹中对合并文件没有影响）。

• 其次，有一个components\paths 文件夹，其中每个文件可以包含一个或多个路径。

• 最后有一个非常空的根 yml 文件。

这是一个将文件重新合并在一起的脚本示例。 https://gist.github.com/bvandenbon/b91c0e39387019daaa813fdcaeac2a51

典型的root.yml 文件如下所示：

openapi: 3.0.1
info:
  title: MyApiServer
  version: "1.0.0"
servers:
  - description: My API server
    url: http://localhost:49361/rs/

具有依赖关系的典型模型文件，如下所示：

PS：我在此处为我的模型名称使用的点分符号不是强制性的，除了 openapi 规范定义的命名之外，没有其他命名限制。但是来自java背景，我更喜欢根据模型所在的子目录来命名模型。但是命名的限制取决于您使用的文档/代码生成器工具。 Swagger UI 没有问题，但代码生成工具确实有一些限制。