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

Question

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

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

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

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

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

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

Answer 1

如果我正确理解了您的需求，那么您只想告诉Generator不要再次生成您现有的类。 如果以上正确，那么您可以像这样配置插件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规范过于正式/明显/过大，无法与外部文件引用imho一起使用。

相反，我更愿意将内容拆分为单独的文件，而不添加来自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背景，我更喜欢根据模型所在的子目录来命名模型。但是命名的局限性取决于所使用的doc /代码生成器工具。 Swagger UI没问题，但是代码生成工具确实有一些限制。