{"id":15091343,"url":"https://github.com/globedaboarder/openapi-generator-wrong-response-body-bug-demo","last_synced_at":"2026-01-04T21:47:36.119Z","repository":{"id":215147228,"uuid":"738213753","full_name":"GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo","owner":"GlobeDaBoarder","description":"This repository is created to showcase a bug in the OpenAPI generator for Spring. The bug appears when using multiple HTTP response codes, of which not all are with response bodies.  Response codes that were specified in the OpenAPI spec to not have any response body will still have response bodies from previous HTTP responses in Swagger UI","archived":false,"fork":false,"pushed_at":"2024-01-02T19:49:10.000Z","size":79,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"bug-showcase","last_synced_at":"2025-03-22T10:48:29.206Z","etag":null,"topics":["bug","java","openapi-generator","openapi-specification","spring","spring-boot","springdoc","springdoc-openapi","swagger-ui"],"latest_commit_sha":null,"homepage":"","language":"Mustache","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GlobeDaBoarder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-02T17:41:17.000Z","updated_at":"2024-01-04T08:46:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"ca4b5c18-4f08-4733-b21b-4a43820b73c7","html_url":"https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo","commit_stats":null,"previous_names":["globedaboarder/openapi-generator-wrong-response-body-bug-demo"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobeDaBoarder%2Fopenapi-generator-wrong-response-body-bug-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobeDaBoarder%2Fopenapi-generator-wrong-response-body-bug-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobeDaBoarder%2Fopenapi-generator-wrong-response-body-bug-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlobeDaBoarder%2Fopenapi-generator-wrong-response-body-bug-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GlobeDaBoarder","download_url":"https://codeload.github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/tar.gz/refs/heads/bug-showcase","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244945590,"owners_count":20536296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bug","java","openapi-generator","openapi-specification","spring","spring-boot","springdoc","springdoc-openapi","swagger-ui"],"created_at":"2024-09-25T10:40:31.427Z","updated_at":"2026-01-04T21:47:36.081Z","avatar_url":"https://github.com/GlobeDaBoarder.png","language":"Mustache","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Response bodies bug in OpenAPI Spring generator\n\n## Table of contents:\n1. [Bug Decription](#bug-description)\n   \n   1.1. [What the bug is](#what-bug)\n   \n   1.2. [Why this is happening](#why)\n\n3. [Proposed solution: bugfix](#solution)\n   \n   2.1. [What should be changed to fix bug](#be-changed)\n   \n   2.2. [Results of the changes in Swagger Annotations](#res1)\n   \n   2.3. [Results of the changes in SwaggerUI: bug fixed](#res2)\n\n## Bug Decription \u003ca name=\"bug-description\"\u003e\u003c/a\u003e\n## ❗ _To reproduce, checkout the `bug-showcase` branch_ \nIt's as simple as:\n- ```bash\n   git clone https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo.git\n  ```\n\n- make sure you are on the `bug-showcase` branch\n- ```bash\n   mvn clean compile\n  ```\n\n- run\n- go to [http://localhost:8080](http://localhost:8080)\n\n  That's it! Made it simple for y'all 😉\n\n### What the bug is \u003ca name=\"what-bug\"\u003e\u003c/a\u003e\n\nThe bug is in how OpenAPI Spring generator generates **Swagger annotation** in [`api.nustache`](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/JavaSpring/api.mustache)\n\nLet's say we have a simple [Dog API](https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/blob/bug-showcase/src/main/resources/openapi.yaml) defined in this OpenAPI spec file:\n\n```yaml\nopenapi: 3.0.3\ninfo:\n  title: Simple test API\n  description: Simple test API\n  version: 1.0.0\n  contact:\n    name: Gleb Ivashyn\n    url: https://github.com/GlobeDaBoarder?tab=repositories\n    email: glebivashyn@gmail.com\nservers:\n  - url: 'https://localhost:8080'\npaths:\n  /dogs/ok-endpoints/:\n    get:\n      summary: Get all dogs\n      operationId: getAllDogs\n      tags:\n        - dogs\n      responses:\n        '200':\n          description: OK\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: '#/components/schemas/Dog'\n  /dogs/ok-endpoints/{id}:\n    delete:\n      summary: Delete dog by id\n      operationId: deleteDogById\n      tags:\n        - dogs\n      parameters:\n        - name: id\n          in: path\n          description: Dog id\n          required: true\n          schema:\n            type: integer\n            format: int64\n      responses:\n        '204':\n          description: No Content\n        '404':\n          description: Not Found\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Error'\n        '400':\n          description: Bad Request\n  /dogs/broken-endpoint/:\n    get:\n      summary: Broken\n      operationId: broken\n      deprecated: true # Done purely for visibility purposes in Swagger UI\n      tags:\n        - dogs\n      responses:\n        '200':\n          description: OK\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: '#/components/schemas/Dog'\n        '204':\n          description: No Content\n        '400':\n          description: Bad Request\ncomponents:\n  schemas:\n    ....\n```\n\nNotice how in our delete methods we have status codes `204` and `400` and how they only have a description _**without a response body**_:\n``` yaml\n... \nresponses:\n  '204':\n    description: No Content\n  '404':\n    description: Not Found\n    content:\n      application/json:\n        schema:\n          $ref: '#/components/schemas/Error'\n  '400':\n    description: Bad Request\n...\n```\n\nand \n\n``` yaml\n...\nresponses:\n  '200':\n    description: OK\n    content:\n      application/json:\n        schema:\n          type: array\n          items:\n            $ref: '#/components/schemas/Dog'\n  '204':\n    description: No Content\n  '400':\n    description: Bad Request\n...\n```\nLogically, we would expect it to be this way in our Swagger UI as well, but surprisingly it isn't that simple. In one case it is like that, but in another one responses `204` and `400` have \na response body that we did not specify.\n\n#### Case 1: proper response codes with no response bodies:\n\nIf we launch the application and go to localhost to view Swagger UI, we will be met with three endpoints.\nLet's take a look at the `/dogs/ok-endpoints/` **DELETE** endpoint:\n![image](https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/assets/74022878/534d31a7-7608-4d70-9dd3-533be810f31a)\n\n\nHere, everything looks just like we expected. `204` and `400` have no response body. Good! There is however a different case.\n\n#### Case 2: `204` and `400` have a response body for some reason... \n\nNow, if we take a look at a different endpoint, which is under `\n  'http://localhost:8090` **GET** and is deprecated (for visibility purposes). The picture is completely different here:\n\n  ![image](https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/assets/74022878/16903a94-e3ba-4f3f-b3fd-7a48e4a50625)\n\nAlthough specified without response bodies, `204` and `400` now have a response body, coming from the previous response. \n\n### Why this is happening \u003ca name=\"why\"\u003e\u003c/a\u003e\n\nIt is hard for me to pinpoint exactly what the reason for this strange behavior is. If we take a look at the generated Swagger UI annotation on controllers, those look fairly normal:\n![image](https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/assets/74022878/372c5188-f046-4307-a7a6-135db6306f81)\n![image](https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/assets/74022878/04e47616-9d01-40d3-a080-c7decb5ef8d1)\n\n\nIn both cases, Swagger annotation does not have any data or schema references that were not defined in OpenAPI spec.\n\nThis leads me to believe that the underlying issue is how **SpringDoc interprets those annotations**. \nIt seems like because the status code `200` comes earlier than codes `204` and `404`, SpringDoc for some reason applies this schema even to responses with no schema defined. \n\nEven though this technically seems like more of a SpringDoc issue, ***It is extremely easy to fix by just slightly adjusting one line in the `api.mustache`  template file of the OpenAPI Spring generator.***\nIt's a simple approach and as a result, SpringDoc doesn't get confused : ) \n\n# Proposed solution: bugfix \u003ca name=\"solution\"\u003e\u003c/a\u003e\n\n## ❗ _To view the proposed bugfix solution, checkout the `bugfix-proposal` branch_\n\nThe main and only change that has to be made to the `api.mustache` file is on the line 176 of the [api mustache file from the official OpenAPi Generator GitHub repo](https://github.com/OpenAPITools/openapi-generator/blob/8b5b5a74c333b809c5a651366656257ec8a6fef3/modules/openapi-generator/src/main/resources/JavaSpring/api.mustache#L176C34-L176C34)\n\n### What should be changed \u003ca name=\"be-changed\"\u003e\u003c/a\u003e\n\nIn the default template, this line looks like this:\n``` mustache\n...\n            }{{/baseType}}){{^-last}},{{/-last}}\n...\n```\n\nTo fix not needed response body generation, all change it to this, [as made in the bugfix branch](https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/blob/af8b92a313a05ec57e809086646ed59ac95d0704/src/main/resources/templates/api.mustache#L176C12-L176C95): \n```\n            }{{/baseType}}{{^baseType}}, content = @Content{{/baseType}}){{^-last}},{{/-last}}\n````\n\nWhat this results in, is instead of having to `@Content` annotation, when no content is specified, it will generate a `@Content` annotation, ***BUT EMPTY ONE***\n\nSee commit info of the fix [here](https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/commit/af8b92a313a05ec57e809086646ed59ac95d0704)\n\n### Results of the changes in Swagger Annotation \u003ca name=\"res1\"\u003e\u003c/a\u003e\nBefore:\n![image](https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/assets/74022878/8069c8f9-6791-456d-831c-477375e990f4)\n\n\nAfter:\n![image](https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/assets/74022878/1a1272c9-fa7a-45c0-87f4-56183847c23e)\n\nAlthough this may seem a bit redundant, it does deal with the bug and doesn't provide that much of clutter and difference. \n\n### Results of the changes in SwaggerUI: bug fixed \u003ca name=\"res2\"\u003e\u003c/a\u003e\n\nAs a result, our \"broken\" endpoint (or to be more accurate, an incorrectly displayed API documentation of an endpoint), now looks just like we would expect:\n\n![image](https://github.com/GlobeDaBoarder/openapi-generator-wrong-response-body-bug-demo/assets/74022878/def4db7a-318b-4d8b-b6c4-2dc232d43a2c)\n\n# That's It!\n\nThanks for reading through and feel free to ask any questions, open issues, or reach out to me directly. I hope this was an informative and needed contribution 🙏\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglobedaboarder%2Fopenapi-generator-wrong-response-body-bug-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglobedaboarder%2Fopenapi-generator-wrong-response-body-bug-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglobedaboarder%2Fopenapi-generator-wrong-response-body-bug-demo/lists"}