Skip to content

Argument useReturnTypeSchema=true is ignored when multiple @ApiResponse are defined #3137

@rodrigo-vizbelis

Description

@rodrigo-vizbelis

Describe the bug
@ApiResponse argument useReturnTypeSchema=true is ignored when multiple @ApiResponse are defined.

To Reproduce
Example when schema for Page<HelloWorld> is generated (second @ApiResponse() is not defined):

@RestController
@RequestMapping({"/api/v1/hello-world"})
public class HelloWorldRestController {

	public record HelloWorld(String message) {

	}

	public record Error(String message) {

	}

	@Operation(
			summary = "Retrieve page of hello world messages",
			tags = {"HelloWorld"}
	)
	@ApiResponses(value = {
			@ApiResponse(
					responseCode = "200",
					useReturnTypeSchema = true,
					content = @Content(
							mediaType = "application/json",
							examples = {
									@ExampleObject(
											name = "Success",
											description = "Successful response",
											value = "..."
									)
							}
					)
			)
//			@ApiResponse(
//					responseCode = "400",
//					content = @Content(
//							mediaType = "application/json",
//							schema = @Schema(implementation = Error.class)
//					)
//			)
	})
	@GetMapping
	public Page<HelloWorld> getHelloWorldPage() {
		return Page.empty();
	}
}

Generated OpenAPI specification before defining second @ApiResponse():

...
  "/api/v1/hello-world": {
    "get": {
      "tags": [
        "HelloWorld"
      ],
      "summary": "Retrieve page of hello world messages",
      "operationId": "getHelloWorldPage",
      "responses": {
        "200": {
          "description": "OK",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PageHelloWorld"
              },
              "examples": {
                "Success": {
                  "description": "Successful response",
                  "value": "..."
                }
              }
            }
          }
        }
      }
    }
  }
...

Generated OpenAPI specification after defining second @ApiResponse():

...
  "/api/v1/hello-world": {
    "get": {
      "tags": [
        "HelloWorld"
      ],
      "summary": "Retrieve page of hello world messages",
      "operationId": "getHelloWorldPage",
      "responses": {
        "200": {
          "description": "OK",
          "content": {
            "application/json": {
              "examples": {
                "Success": {
                  "description": "Successful response",
                  "value": "..."
                }
              }
            }
          }
        },
        "400": {
          "description": "Bad Request",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Error"
              }
            }
          }
        }
      }
    }
  }
...

Expected behavior
Expected OpenAPI specification:

...
  "/api/v1/hello-world": {
    "get": {
      "tags": [
        "HelloWorld"
      ],
      "summary": "Retrieve page of hello world messages",
      "operationId": "getHelloWorldPage",
      "responses": {
        "200": {
          "description": "OK",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PageHelloWorld"
              },
              "examples": {
                "Success": {
                  "description": "Successful response",
                  "value": "..."
                }
              }
            }
          }
        },
        "400": {
          "description": "Bad Request",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Error"
              }
            }
          }
        }
      }
    }
  }
...

Version
springdoc-openapi-starter-webmvc-ui: 2.8.13

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions