Swagger описание ошибок

OAS 3 This guide is for OpenAPI 3.0. If you use OpenAPI 2.0, see our OpenAPI 2.0 guide.

An API specification needs to specify the responses for all API operations. Each operation must have at least one response defined, usually a successful response. A response is defined by its HTTP status code and the data returned in the response body and/or headers. Here is a minimal example:

paths:
  /ping:
    get:
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: pong

Response Media Types

An API can respond with various media types. JSON is the most common format for data exchange, but not the only one possible. To specify the response media types, use the content keyword at the operation level.

paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfUsers'
            application/xml:
              schema:
                $ref: '#/components/schemas/ArrayOfUsers'
            text/plain:
              schema:
                type: string

  # This operation returns image
  /logo:
    get:
      summary: Get the logo image
      responses:
        '200':
          description: Logo image in PNG format
          content:
            image/png:
              schema:
                type: string
                format: binary

More info: Media Types.

HTTP Status Codes

Under responses, each response definition starts with a status code, such as 200 or 404. An operation typically returns one successful status code and one or more error statuses. To define a range of response codes, you may use the following range definitions: 1XX, 2XX, 3XX, 4XX, and 5XX. If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. Each response status requires a description. For example, you can describe the conditions for error responses. Markdown (CommonMark) can be used for rich text representation.

      responses:
        '200':
          description: OK
        '400':
          description: Bad request. User ID must be an integer and larger than 0.
        '401':
          description: Authorization information is missing or invalid.
        '404':
          description: A user with the specified ID was not found.
        '5XX':
          description: Unexpected error.

Note that an API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance. However, it is expected to cover successful responses and any known errors. By “known errors” we mean, for example, a 404 Not Found response for an operation that returns a resource by ID, or a 400 Bad Request response in case of invalid operation parameters.

Response Body

The schema keyword is used to describe the response body. A schema can define:

• an object or an array — typically used with JSON and XML APIs,
• a primitive data type such as a number or string – used for plain text responses,
• a file – (see below).

Schema can be defined inline in the operation:

      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The user ID.
                  username:
                    type: string
                    description: The user name.

or defined in the global components.schemas section and referenced via $ref. This is useful if multiple media types use the same schema.

      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: The user ID.
        username:
          type: string
          description: The user name.

Response That Returns a File

An API operation can return a file, such as an image or PDF. OpenAPI 3.0 defines file input/output content as type: string with format: binary or format: base64. This is in contrast with OpenAPI 2.0, which uses type: file to describe file input/output content. If the response returns the file alone, you would typically use a binary string schema and specify the appropriate media type for the response content:

paths:
  /report:
    get:
      summary: Returns the report in the PDF format
      responses:
        '200':
          description: A PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary

Files can also be embedded into, say, JSON or XML as a base64-encoded string. In this case, you would use something like:

paths:
  /users/me:
    get:
      summary: Returns user information
      responses:
        '200':
          description: A JSON object containing user name and avatar
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                  avatar:          # <-- image embedded into JSON
                    type: string
                    format: byte
                    description: Base64-encoded contents of the avatar image

anyOf, oneOf

OpenAPI 3.0 also supports oneOf and anyOf, so you can specify alternate schemas for the response body.

      responses:
        '200':
          description: A JSON object containing pet information
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Cat'
                  - $ref: '#/components/schemas/Dog'
                  - $ref: '#/components/schemas/Hamster'

Empty Response Body

Some responses, such as 204 No Content, have no body. To indicate the response body is empty, do not specify a content for the response:

      responses:
        '204':
          description: The resource was deleted successfully.

Responses from an API can include custom headers to provide additional information on the result of an API call. For example, a rate-limited API may provide the rate limit status via response headers as follows:

HTTP 1/1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 2016-10-12T11:00:00Z

{ ... }

You can define custom headers for each response as follows:

paths:
  /ping:
    get:
      summary: Checks if the server is alive.
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per hour.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: The number of requests left for the time window.
            X-RateLimit-Reset:
              schema:
                type: string
                format: date-time
              description: The UTC date/time at which the current rate limit window resets.

Note that, currently, OpenAPI Specification does not permit to define common response headers for different response codes or different API operations. You need to define the headers for each response individually.

Default Response

Sometimes, an operation can return multiple errors with different HTTP status codes, but all of them have the same response structure:

      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

        # These two error responses have the same schema
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

You can use the default response to describe these errors collectively, not individually. “Default” means this response is used for all HTTP codes that are not covered individually for this operation.

      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

        # Definition of all error statuses
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Reusing Responses

If multiple operations return the same response (status code and data), you can define it in the responses section of the global components object and then reference that definition via $ref at the operation level. This is useful for error responses with the same status codes and response body.

paths:
  /users:
    get:
      summary: Gets a list of users.
      response:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfUsers'
        '401':
          $ref: '#/components/responses/Unauthorized'   # <-----
  /users/{id}:
    get:
      summary: Gets a user by ID.
      response:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'   # <-----
        '404':
          $ref: '#/components/responses/NotFound'       # <-----

# Descriptions of common components
components:
  responses:
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    # Schema for error response body
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message

Note that responses defined in components.responses are not automatically applied to all operations. These are just definitions that can be referenced and reused by multiple operations.

Linking Response Values to Other Operations

Certain values in the response could be used as parameters to other operations. A typical example is the «create resource» operation that returns the ID of the created resource, and this ID can be used to get that resource, update or delete it. OpenAPI 3.0 provides the links keyword to describe such relationships between a response and other API calls. For more information, see Links.

FAQ

Can I have different responses based on a request parameter? Such as:

GET /something -> {200, schema_1}
GET /something?foo=bar -> {200, schema_2}

In OpenAPI 3.0, you can use oneOf to specify alternate schemas for the response and document possible dependencies verbally in the response description. However, there is no way to link specific schemas to certain parameter combinations.

Reference

Response Object

MediaType Object

Components Object

Did not find what you were looking for? Ask the community
Found a mistake? Let us know

Error Declaration

The API Declaration should describe how the different errorResponses map to the
business logic of the API. For instance, if a 404 is returned, it may be due to a variety
of reasons—invalid resource, object cannot be found, invalid parameter, etc. While
the HTTP response codes can be interpreted by the consumer correctly, often they are
ambiguous and can benefit from some documentation.

The errorResponse object contains just two fields, as shown below:

"errorResponses":[
  {
    "code": 400,
    "reason": "Raised if a user supplies an invalid username format"
  },
  {
    "code": 404,
    "reason": "The user cannot be found"
  }
],

code. This is the HTTP response code which causes the error condition

reason. This is a text explanation of what will cause the error condition

Documenting error codes definition in Swagger API contract

  @Bean
  public Docket swaggerSettings() {
    ApiSelectorBuilder builder = new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(
        new ApiInfoBuilder()
          .title("Response errorCodes table")
          .description(RestResponse.generateErrorsDocumentation().toString())
          .build()
      )
      ...
      .select();
    return builder.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
        .paths(PathSelectors.any())
        .build()
        .useDefaultResponseMessages(false);
  }

API Platform — How to add response code in Swagger UI using decorator to add 400, 404, 500 response code so client know the response in adwance

$openApi->getPaths()->addPath('/api/grumpy_pizzas/{id}', $pathItem->withGet(
            $operation->withParameters(array_merge(
                $operation->getParameters(),
                [new Model\Parameter('fields', 'query', 'Fields to remove of the output')]
            ))
        ));

private function setErrorResponseDescriptions(OpenApi $openApi): OpenApi
{
    $schemas = $openApi->getComponents()->getSchemas();
    $schemas['Error'] = [
        'type'       => 'object',
        'properties' => [
            'type' => [
                'type'     => 'string',
                'readOnly' => true,
            ],
            'title' => [
                'type'     => 'string',
                'readOnly' => true,
            ],
            'detail' => [
                'type'     => 'string',
                'readOnly' => true,
            ],
        ],
    ];
    $schemas['ValidationError'] = [
        'type'       => 'object',
        'properties' => [
            'type' => [
                'type'     => 'string',
                'readOnly' => true,
            ],
            'title' => [
                'type'     => 'string',
                'readOnly' => true,
            ],
            'detail' => [
                'type'     => 'string',
                'readOnly' => true,
            ],
            'validations' => [
                'type'     => 'array',
                'readOnly' => true,
                'items'    => [
                    'type'       => 'object',
                    'properties' => [
                        'propertyPath' => [
                            'type'     => 'string',
                            'readOnly' => true,
                        ],
                        'message' => [
                            'type'     => 'string',
                            'readOnly' => true,
                        ],
                    ]
                ]
            ]
        ],
    ];
    foreach ($openApi->getPaths()->getPaths() as $path => $pathItem) {
        foreach (['PUT', 'POST', 'PATCH', 'GET'] as $method) {
            $item = $pathItem->{'get' . ucfirst($method)}();
            if ($item) {
                $item->addResponse(
                    new Model\Response(
                        description: 'Unauthorized',
                        content: new \ArrayObject([
                            'application/problem+json' => [
                                'schema' => [
                                    '$ref' => '#/components/schemas/Error',
                                ],
                            ],
                        ])
                    ),
                    '401'
                );
                if ('GET' !== $method) {
                    $item->addResponse(
                        new Model\Response(
                            description: 'Bad request',
                            content: new \ArrayObject([
                                'application/problem+json' => [
                                    'schema' => [
                                        '$ref' => '#/components/schemas/ValidationError',
                                    ],
                                ],
                            ])
                        ),
                        '400'
                    );
                } else {
                    $item->addResponse(
                        new Model\Response(
                            description: 'Not Found',
                            content: new \ArrayObject([
                                'application/problem+json' => [
                                    'schema' => [
                                        '$ref' => '#/components/schemas/Error',
                                    ],
                                ],
                            ])
                        ),
                        '404'
                    );
                }
            }
        }
    }
    return $openApi;
}

How can I display error code description in sample code section?

public class ExceptionResponse {
    private Instant time;
    private int status;
    private String error;
    private String exception;
    private String message;
}

public static final String exampleInternalError = "{\r\n" + "  \"status\": 500,\r\n" + "\"error\": Bad Request,\r\n"
            + "  \"message\": \"Your custome message goes here\"\r\n" + "}";

@ApiResponse(responseCode = "400", description = "Bad Request", 
                  content = @Content(schema = @Schema(implementation = ExceptionResponse .class), 
                        examples = @ExampleObject(description = "Bad Request", value = exampleInternalError)))

@ApiResponse(responseCode = "400", description = "Bad Request", 
content = @Content(schema = @Schema(implementation = String.class), 
              examples = @ExampleObject(description = "Bad Request", value = "\"Your details about error code and error message goes here")))

Response status is 500 for swagger appears once HttpGet for a specific object is implemented