OpenAPITools / OpenAPITools/openapi-generator

[BUG] openapi-yaml generator does not handle requestBody references correctly

Open
#4,575 3 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Description

I use the OpenAPI generator to merge a set of OpenAPI yaml files into one single file. That is done within a Maven build using the openapi-generator-maven-plugin.

After executing the generator the requestBody parts in the resulting yaml file have duplicated content. One version of the content is referenced correctly using the $ref keyword. The duplicated content is directly printed inline after the line starting with the $ref keyword.

As an effect the Swagger UI (tested with editor.swagger.io) does not show the requestBody data (neither examples nor schema).

openapi-generator version

I use the openapi-generator-maven-plugin version 4.2.1. It uses the openapi-generator 4.2.1 as a dependency. The problem can be reproduced with all available 4.x.x versions.

OpenAPI declaration file content or url

There are three files in the src/main/resources folder:

openapi.yaml:

openapi: 3.0.2

info:
  version: 9.9.9
  title: requestBody bug report

servers:
  - url: http://localhost:8080

tags:
  - name: Bugreport

paths:
  /test:
    post:
      tags: 
        - Bugreport
      operationId: POST_Test
      requestBody:
        description: Example Request
        content:
          application/json:
            schema:
              type: object
              required: [
                foo
              ]
              properties:
                foo:
                  $ref: ./content.yaml
      responses:
        201:
          description: Example Response
          content:
            application/json:
              schema:
                type: object
                required: [
                  bar
                ]
                properties:
                  bar:
                    $ref: ./content.yaml
          headers:
            Location:
              description: Created Resource
              schema:
                type: string
                example: http://localhost:8080/test/999

content.yaml:

type: object
required: [
  baz
]
properties:
  baz:
    $ref: ./baz.yaml

baz.yaml:

type: string
example: baz

And in the root there is a Maven pom.xml file:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>test</groupId>
    <artifactId>test</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <build>
        <plugins>
            <plugin>
                <groupId>org.openapitools</groupId>
                <artifactId>openapi-generator-maven-plugin</artifactId>
                <version>4.2.1</version>
                <executions>
                    <execution>
                        <id>merge-openapi-yaml</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
                            <generatorName>openapi-yaml</generatorName>
                            <configOptions>
                                <outputFile>openapi.yaml</outputFile>
                            </configOptions>
                            <output>${project.build.directory}</output>
                            <skipValidateSpec>false</skipValidateSpec>
                            <strictSpec>true</strictSpec>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>
Command line used for generation

Run mvn clean install.

Steps to reproduce

After running the generation there is an openapi.yaml file being created in the target folder. It looks like:

openapi: 3.0.2
info:
  title: requestBody bug report
  version: 9.9.9
servers:
- url: http://localhost:8080
tags:
- name: Bugreport
paths:
  /test:
    post:
      operationId: POST_Test
      requestBody:
        $ref: '#/components/requestBodies/inline_object'
        content:
          application/json:
            schema:
              properties:
                foo:
                  $ref: '#/components/schemas/content'
              required:
              - foo
              type: object
        description: Example Request
      responses:
        201:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_201'
          description: Example Response
          headers:
            Location:
              description: Created Resource
              explode: false
              schema:
                example: http://localhost:8080/test/999
                type: string
              style: simple
      tags:
      - Bugreport
components:
  requestBodies:
    inline_object:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_object'
  schemas:
    content:
      example:
        baz: baz
      properties:
        baz:
          example: baz
          type: string
      required:
      - baz
      type: object
    baz:
      example: baz
      type: string
    inline_object:
      properties:
        foo:
          $ref: '#/components/schemas/content'
      required:
      - foo
      type: object
    inline_response_201:
      example:
        bar:
          baz: baz
      properties:
        bar:
          $ref: '#/components/schemas/content'
      required:
      - bar

This results into a buggy Swagger UI representation due to the duplicated content: request.png

The response part looks ok and I would expect to have the request part looking alike: response.png

I would expect the yaml to be generated as follows:

openapi: 3.0.2
info:
  title: requestBody bug report
  version: 9.9.9
servers:
- url: http://localhost:8080
tags:
- name: Bugreport
paths:
  /test:
    post:
      operationId: POST_Test
      requestBody:
        $ref: '#/components/requestBodies/inline_object'
      responses:
        201:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_201'
          description: Example Response
          headers:
            Location:
              description: Created Resource
              explode: false
              schema:
                example: http://localhost:8080/test/999
                type: string
              style: simple
      tags:
      - Bugreport
components:
  requestBodies:
    inline_object:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_object'
  schemas:
    content:
      example:
        baz: baz
      properties:
        baz:
          example: baz
          type: string
      required:
      - baz
      type: object
    baz:
      example: baz
      type: string
    inline_object:
      properties:
        foo:
          $ref: '#/components/schemas/content'
      required:
      - foo
      type: object
    inline_response_201:
      example:
        bar:
          baz: baz
      properties:
        bar:
          $ref: '#/components/schemas/content'
      required:
      - bar

This would result into a proper Swagger UI representation: request-corrected.png

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Run mvn clean install with the provided pom.xml and the openapi.yaml, content.yaml, and baz.yaml files, then inspect target/openapi.yaml. Start at the openapi-yaml generator and compare the generated requestBody with the expected output: the requestBody should contain only its $ref, without duplicated inline content, while the response remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.