OpenApi 生成器在 YAML 文件规范中引用外部 POJO

Question

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

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

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

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

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

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

Answer 1

理论：

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

现实：

话虽如此，我宁愿完全不使用它。 openapi 规范太 formal/explicit/bloated 无法使用外部文件引用，恕我直言。

相反，我更喜欢将内容拆分到单独的文件中而不从根 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/code 生成器工具。 Swagger UI 没有问题，但代码生成工具确实有一些限制。

Answer 2

如果我对你的需求理解正确，你只是想告诉生成器不要再次生成你现有的 class。如果上面是正确的，那么你可以像这样配置插件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 定义生成 class，而是使用现有定义。

OpenApi 生成器在 YAML 文件规范中引用外部 POJO

OpenApi Generator reference an external POJO in YAML file specification

swagger-codegen

openapi-generator