[OPENAPI] [swagger-codegen-maven-plugin] Parameters and responses are copied to components/parameters and components/responses, but not referenced to

Description

When using references to parameters and responses from another file or current file, after generation the references are erased and the content is copied, but duplicated to components/parameters and components/responses.

When using schema validation tools on this contract, it will flag vulnerability: unused component definition.

Swagger-codegen version

           <plugin>
                <groupId>io.swagger.codegen.v3</groupId>
                <artifactId>swagger-codegen-maven-plugin</artifactId>
                <version>3.0.55</version>
            </plugin>

Swagger declaration file content or url

common.yaml

openapi: 3.0.1
info:
  title: Common
  version: 1.56.0
  description: Contains Common objects to be reused

paths: {}

components:
  parameters:
    DummyHeader:
      in: header
      name: Dummy-Header
      description: Dummy header
      example: '463ac4'
      schema:
        type: string

  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          description: The error code
          example: 200
        status:
          type: string
          description: The error status
          example: 'NOT_FOUND'
          minLength: 1
          maxLength: 256
        description:
          type: string
          description: The error description
          example: Description
          minLength: 1
          maxLength: 256

    ApiHealth:
      type: object
      description: API Health response object
      required:
        - status
      properties:
        status:
          type: string
          description: Overall connect platform availability status
          example: "UP"
          enum:
            - UP
            - DOWN
            - DEGRADED
        statusMessage:
          type: string
          description: Additional informational message
          example: "Not Used"

main.yaml

openapi: 3.0.3
info:
  title: Service API
  description: Service API
  contact:
    name: API Support
    url: https://dummy/support
    email: apisupport@dummy.com
  version: 1.0.0
servers:
  - url: /api
    description: Used with swagger-ui for any server
tags:
  - name: Health
    description: Health
paths:
  /health:
    get:
      tags:
        - Health
      summary: Returns the status
      operationId: getHealthStatus
      description: Returns the health status
      parameters:
        - $ref: 'common.yaml#/components/parameters/DummyHeader'
        - $ref: '#/components/parameters/Dummy2Header'
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: 'common.yaml#/components/schemas/ApiHealth'
        "400":
          $ref: '#/components/responses/BadRequest'
        "404":
          $ref: 'common.yaml#/components/responses/NotFound'

components:
  parameters:
    Dummy2Header:
      in: header
      name: Dummy2-Header
      required: false
      description: Dummy 2 header
      example: 'W9114'
      schema:
        type: string
        maxLength: 256
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: 'common.yaml#/components/schemas/Error'

Command line used for generation

maven pom.xml definition:

    <build>
        <plugins>
            <plugin>
                <groupId>io.swagger.codegen.v3</groupId>
                <artifactId>swagger-codegen-maven-plugin</artifactId>
                <version>${swagger-codegen-maven-plugin.v3.version}</version>
                <executions>
                    <execution>
                        <id>convert-main-service</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <inputSpec>${project.basedir}/src/main/resources/main.yaml</inputSpec>
                            <output>${project.basedir}/target/classes</output>
                            <language>openapi-yaml</language>
                            <configOptions>
                                <outputFile>main.yaml</outputFile>
                            </configOptions>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
       ...

Steps to reproduce

• run mvn compile
• generated file:

openapi: 3.0.3
info:
  title: Service API
  description: Service API
  contact:
    name: API Support
    url: https://dummy/support
    email: apisupport@dummy.com
  version: 1.0.0
servers:
- url: /api
  description: Used with swagger-ui for any server
tags:
- name: Health
  description: Health
paths:
  /health:
    get:
      tags:
      - Health
      summary: Returns the status
      description: Returns the health status
      operationId: getHealthStatus
      parameters:
      - name: Dummy-Header
        in: header
        description: Dummy header
        schema:
          type: string
        example: 463ac4
      - name: Dummy2-Header
        in: header
        description: Dummy 2 header
        required: false
        style: simple
        explode: false
        schema:
          maxLength: 256
          type: string
        example: W9114
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiHealth'
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ApiHealth:
      required:
      - status
      type: object
      properties:
        status:
          type: string
          description: Overall connect platform availability status
          example: UP
          enum:
          - UP
          - DOWN
          - DEGRADED
        statusMessage:
          type: string
          description: Additional informational message
          example: Not Used
      description: API Health response object
    Error:
      type: object
      properties:
        code:
          type: integer
          description: The error code
          example: 200
        status:
          maxLength: 256
          minLength: 1
          type: string
          description: The error status
          example: NOT_FOUND
        description:
          maxLength: 256
          minLength: 1
          type: string
          description: The error description
          example: Description
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Dummy2Header:
      name: Dummy2-Header
      in: header
      description: Dummy 2 header
      required: false
      style: simple
      explode: false
      schema:
        maxLength: 256
        type: string
      example: W9114
    DummyHeader:
      name: Dummy-Header
      in: header
      description: Dummy header
      schema:
        type: string
      example: 463ac4

Conclusion: All parameters and responses are copied to parameters after generation and not referenced to. The components/schemas are referenced as expected. In this case, the components/parameters objects are present, but not referenced to.

Start with the common.yaml and main.yaml declarations and the swagger-codegen-maven-plugin configuration in pom.xml, then run mvn compile to compare the generated file with the expected references. Trace how external and local parameter and response references are processed; done means generated components/parameters and components/responses remain referenced instead of being duplicated inline, while schema references continue to work.