OpenApi Generator reference an external POJO in YAML file specification

问题

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) wich 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'
...

wich get generated by OpenApi plugin and then I map it to SignatureNotification that already exist and have 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 ?

回答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.

回答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.

来源：https://stackoverflow.com/questions/59072297/openapi-generator-reference-an-external-pojo-in-yaml-file-specification

标签

swagger-codegen

openapi-generator