search

openapi-tools / swagger-maven-plugin

Maven plugin to activate the Swagger Core library to generate OpenAPI documentation.
MIT License
70 stars 45 forks source link

Creating component definition #67

Open ktalebian opened 3 years ago

ktalebian commented 3 years ago

I'm using the default configuration in my pom:

<configuration>
    <resourcePackages>
        <resourcePackage>com.myapp.resource</resourcePackage>
    </resourcePackages>
    <outputDirectory>${basedir}/target/</outputDirectory>
    <outputFilename>my-api</outputFilename>
    <outputFormats>JSON,YAML</outputFormats>
    <prettyPrint>true</prettyPrint>
</configuration>

I need to manually define certain of the external component schemas because our code-gen library is not able to understand what this plugin generates. For that reason, for such modules, I'm annotating the component with @Schema(ref = "PackageName"). This plugin then successfully generates the open-api definition and references the components correctly.

However, the component itself becomes a self reference component:

components:
  schema:
    PackageName:
      $ref: '#/components/schemas/PackageName'

Instead, I want to be able to define this component myself so I can set it to be

components:
  schema:
    PackageName:
      type: object
      x-jvm-type: PackageName
      description: My awesome description
      example: 1234

I created a feature request here https://github.com/openapi-tools/swagger-maven-plugin/issues/66 since securitySchema can now be defined in the pom configuration. In the meantime, I wanted to know if there are any workarounds to get this to work?