Error response with example content using annotations

[Singularitarian]

Hi,

I am trying to document an api error response with  a example of the json body. I couldn't find an example or a fitting annotation. Playing around with the swagger editor I could at least get something that looks like the result I want to achieve.

      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Pet"
        400:
          description: "Invalid ID supplied"
          schema:
            $ref: "#/definitions/ApiResponse"
          examples: 
            properties:
              code: 42
              message: "Invalid ID supplied"

How can I do this with annotations?

I want to add that it is a very specific error message, so I don't need to reuse it.

[frantuma · Accepted solution]

In swagger-core v1 / OpenAPI 2.0 used in your snippet (e.g. `io.swagger:swagger-jaxrs:1.5.22-SNAPSHOT`) this is not supported in versions < 1.5.22-SNAPSHOT (latest snapshot version available on sonatype); in latest version you can achieve it like:

@Api
@Path("/v1")
public class ResponseExampleResource {
  @Path("path")
  @ApiResponses({
    @ApiResponse(code = 200, message = "successful operation", response = Pet.class),
    @ApiResponse(code = 400, message = "Invalid ID supplied", response = ApiResponse.class,
		  examples = @Example(value =
        {
          @ExampleProperty(mediaType = "application/json", value = "{\"code\" : \"42\", \"message\" : \"Invalid ID supplied\"}")
        }
		  ))
  })
  @GET
  public Response responseExample() {
    return null;
  }
}

which resolves into:

paths:
  /v1/path:
    get:
      operationId: "getResource"
      parameters: []
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Pet"
        400:
          description: "Invalid ID supplied"
          examples:
            application/json:
              code: "42"
              message: "Invalid ID supplied"
          schema:
            $ref: "#/definitions/ApiResponse"

Alternatively this is fully supported in swagger-core v2 / OpenAPI 3.0 (e.g. `io.swagger.core.v3:swagger-jaxrs2:2.0.6`), for example:

class GetOperationWithResponseExamples {
  @Operation(
    operationId = "responseExample",
    responses = {
      @ApiResponse(
        responseCode = "200",
        description = "successful operation",
        content = @Content(
          mediaType = "application/json",
          schema = @Schema(implementation = Pet.class)
        )
      ),
      @ApiResponse(
        responseCode = "400",
        description = "Invalid ID supplied",
        content = @Content(
          mediaType = "application/json",
          schema = @Schema(implementation = ApiResponse.class),
          examples = {
            @ExampleObject(
              name = "Error-42",
              value = "{\"code\": \"42\", \"message\" : \"Invalid ID supplied\"}"
						)
          }
        )
      )
    }
  )
  @GET
  @Path("/path")
  public void responseExample() {
  }
}

resolving to:

paths:
  /path:
    get:
      operationId: responseExample
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        400:
          description: Invalid ID supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              examples:
                Error-42:
                  description: Error-42
                  value:
                    code: "42"
                    message: Invalid ID supplied