4

I am working on a rest api using java spring boot framework, and I tried using springdoc-openapi to generate endpoints documentation, I followed this tutorial and made a documentation, the only problem is when I try to set multiple descriptions for the same Http Error code (like the 404 bellow) only the first one is shown in the generated doc.

@ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Task updated successfully",
                    content = {@Content(mediaType = "application/json",
                            schema = @Schema(implementation = Task.class))}),
            @ApiResponse(responseCode = "400", description = "Friend email equal to user email",
                    content = @Content),
            @ApiResponse(responseCode = "401", description = "Invalid Id Token",
                    content = @Content),
            @ApiResponse(responseCode = "404", description = "Friend not found",
                    content = @Content),
            @ApiResponse(responseCode = "404", description = "Friend email is null",
                    content = @Content),
            @ApiResponse(responseCode = "404", description = "Task not found",
                    content = @Content)})

The result is shown below: enter image description here\

Is it possible to define multiple descriptions (not @Schema) for the same response code? (I already searched but I only found how to set multiple schemas so far)

Isu
  • 330
  • 1
  • 4
  • 16
  • 2
    I don't think it is possible. One possible workaround is merging all descriptions into one. `@ApiResponse(responseCode = "404", description = "Friend not found / Friend email is null / Task not found", content = @Content),` – João Dias Jan 30 '22 at 18:12
  • @JoãoDias that's what I thought of too, at first it seemed more natural to just duplicate the code and change the description. – Isu Jan 30 '22 at 18:33
  • 1
    And in fact, it is, but I don't think that is supported, hence the workaround. – João Dias Jan 30 '22 at 18:34

1 Answers1

1

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#responsesObject states that Responses object contains Any HTTP status code can be used as the property name, but only one property per code - meaning you can't repeat a status code in the resulting swagger, one status code = one response object. Similarly, it defines a single description field in Response object.

As such your problem is not with springdoc but with the OpenAPI specification - there is no such thing as "multiple descriptions for the same HTTP error code" allowed in the specification for the documentation you're trying to generate.

In general, when having trouble with a tool that generates specification try to write what you have in mind by hand and work backwards from there.

Deltharis
  • 2,320
  • 1
  • 18
  • 29
  • Looks like it's possible using "oneOf" though : https://stackoverflow.com/questions/36576447/swagger-specify-two-responses-with-same-code-based-on-optional-parameter – Tristan Feb 03 '23 at 10:46
  • @Tristan It is not. `oneOf`, `anyOf` and `allOf` only pertain to Schema element specifically. https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/ – Deltharis Feb 03 '23 at 10:57