Specify response type for springdoc/io.swagger.core.v3 "ApiResponse"

Question

I have an @RestController endpoint defined as

    @GetMapping(value = "/end/point/{id}")
    public ResponseEntity<Boolean> endpoint(
            @PathVariable("id") @NotBlank @Pattern(regexp ="^[A-Za-z]$") String cdsId){
...
conditions to return boolean
...
    }

I want the OpenApi3 documentation for this to look something like the following. Specifically, I do not want a "content" section, but instead want to be able to define the response type as such:

"200": {
    "description": "OK",
    "type": "boolean"
}

However, using springdoc/io.swagger.core.v3 ApiResponses/ApiResponse like the following:

    @ApiResponses(value = {
            @ApiResponse(),
            @ApiResponse(responseCode = "200", description = "OK" )})

produces

"200": {
   "description":"OK",
    "content": {
        "*/*": {
            "schema": {
                "type": "boolean"
            }
        }
    }
}

I do not want the "content" section at all, as the security scan says that we are running labels it incorrect. At the same time, I want to do this programatically so that I don't have to manually change it every time I retrieve the Api Docs from my app. ApiResponse type does not provide a "type" field and automatically generates "content". Can I handle this in the ApiResponse class?

Answer 1

What is OpenAPI's Response Object?

As outlined in the OpenAPI specification, the response object can have the below properties

• description - Some description about the response that's returned.
• headers - Specifies any additional headers that returned as part of the response. An example is the Set-Cookie header, which can be optionally set as per the requirement. Note that Content-Type isn't a response header but is considered as entity-headers as defined in RFC-7231, section 3.
• content - The actual response object (a plain string is also an object) returned as part of the response.
• links - A map of operational links. An example would be, the links to next/previous/first/last pages when paging is implemented in a search operation.

A closer look at the content property

The property takes in a Map of String (denoting the response code) and MediaType object (denoting the response body).

200:
  description: successful operation
  content:
    application/xml:
      schema:
        type: array
        items:
          $ref: '#/components/schemas/Pet'
    application/json:
      schema:
        type: array
        items:
          $ref: '#/components/schemas/Pet'
400:
  description: Bad Request
  content: {}

In the above example 200 and 400 represent the response codes. When we look into the content for the 200 response, it tells that the response can either be in XML or JSON format as specified in the Content-Type header of the request. For the 400, an empty content ({}) means that no response-body will be returned.

Under each content-type, the schema describes the object that'll be returned for the given response code. For the 200 response it tells that an array will be returned that'll consist of items of the type Pet.

Now, to answer your question.

You can NOT define the response as you said in the below example

"200": {
    "description": "OK",
    "type": "boolean"
}

This is strictly against the specification and when you try this in the swagger-editor, it'll indicate an error due to invalid schema.

The error that's shown in the spec editor is shown below.

The error in the Swagger-UI is shown below