OpenApi Generator reference an external POJO in YAML file specification

Question

I'm using OpenApi v3.3.4 (formerly called Swagger CodeGen) maven plugin to generate my rest controller via api.yml files where I describe all the operations I want to expose.

In my use case, I want to expose a method POST: handleNotification(@RequestBody SignatureNotification notification) which its request body's type is generated via another maven-plugin in /targer folder.

Actually I'm defining SignatureNotification in Componentspart of my .yml file:

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

Which gets generated by OpenApi plugin and then I map it to SignatureNotification that already exists and has the same attributes.

I'm not very satisfied with this solution so I want to know if there is a way to tell OpenApi Generator to use an external object as a reference?

Landy

Answer 1

If I understand your needs correctly, you just want to tell generator not to generate again your existing class. If above is correct, then you can configure plugin importMappings like this:

<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>

With this config, openapi generator won't generate class from SignatureNotification definition, instead it will use existing one.

Gery

thank you so much ! That's works well and I just want to mention that in the .yml file we need to define SignatureNotification in components area having as type: object – Landy

@Ghassen. Thank you for this very helpful discussion. I've tried the same approach, where I'm mapping an external Object from a different package. when I do mvn clean compile, the generator is complaining about this object reference(the Object and package are not part of the target folder of the generator), the code is correct and generated as expected. is there any way to avoid the compilation error? (package dose not exist) – Pickerelweed

Answer 2

The Theory:

According to the openapi spec, a $ref can also be a reference to an external file. You can read all about it here.

Reality:

Having said that, I prefer to not use it at all. The openapi spec is too formal/explicit/bloated to work with external file references, imho.

Instead, I prefer to split the content in separate files without adding references from the root yml file.

I keep my files small. And once I want to process them by a tool, I just merge everything back together. Writing a script to merge them actually is not that hard.

• I create individual files in the components\schemas folder. Each file contains one or multiple model definitions. I can basically put them in any subfolder. (arranging them in subfolders has no impact on the merged file).

• And secondly there is a components\paths folder where each file can contain one or multiple paths.

• Finally there is a root yml file which is pretty empty.

Here is an example of a script to merge the files back together. https://gist.github.com/bvandenbon/b91c0e39387019daaa813fdcaeac2a51

A typical root.yml file looks like this:

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

A typical model file with dependencies, looks like this:

PS: the dotted-notation which I use here for my model names is not mandatory, there are no restrictions in the naming other than the ones defined by the openapi spec. But coming from a java background, I prefer to name the models according to the subdirectory they are in. But the limitations of the naming are subject to the doc/code generator tools you use. Swagger UI has no problems with it, but code generation tools do have some limitations.

Jolee

thank you so much for the explanation it's very clear but my goal was to call an external java class and the solution proposed by @Gery above worked fine for me :) – Landy