Forum Discussion

Singularitarian's avatar
Singularitarian
Frequent Visitor
6 years ago

Error response with example content using annotations

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.

  • 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

     

  • 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