Handling OpenAPI Errors

By default, rororo.openapi.setup_openapi() enables usage of aiohttp_middlewares.error.error_middleware(), which in same time provides human readable JSON errors for:

  • Security error

  • Request parameter validation error

  • Request body validation error

  • Response data validation error

Document below describes how exactly those errors handled, and what changes to OpenAPI Schema you might add to support given error responses.

Security Errors

OpenAPI 3 schema provide a way to “secure” operation via security schemes. As of rororo 2.0.0 version next security schemes are supported:

  • HTTP

    • Basic

    • Bearer

  • API Key

Unfortunately OpenID & OAuth 2 security schemas not yet supported.

Under the hood rororo uses next logic for generating security error,

  • When an operation is guarded with one and only security scheme of HTTP Basic authentication and Authorization header is missed or contains wrong data - 401 Unauthenticated error raised

  • If an operation guarded with other security scheme or with multiple security schemes and security data is missed in request - 403 Access Denied error raised

Both of given errors results in next JSON:

{
    "detail": "Not authenticated"
}

Only difference is response status code & additional www-authenticate: basic header in case of missing HTTP Basic Auth details.

Important

rororo does not intend to check, whether authentication data is valid or not, so aiohttp.web application should make the authentication by itself. Most reliable way of doing that by providing @login_required decorator as done in Hobotnica example.

Request Parameter Validation Errors

When request parameter is missed, when required, missed, has empty, or invalid value openapi-core raises an OpenAPIParameterError. rororo handles given error and wraps it into ValidationError.

For example, when operation is required X-GitHub-Username header parameter, missing it in request will result in 422 Unprocessable Entity response with next JSON content:

{
    "detail": [
        {
            "loc": [
                "parameters",
                "X-GitHub-Username"
            ],
            "message": "Required parameter"
        }
    ]
}

Request Body Validation Errors

TODO

Response Data Validation Errors

TODO

OpenAPI Schemas

You might need to update your OpenAPI 3 Schemas by using next responses components.

Default Error

components:
  responses:
    DefaultError:
      description: "Unhandled error."
      content:
        application/json:
          schema:
            type: "object"
            properties:
              detail:
                type: "string"
                minLength: 1
            required: ["detail"]

Validation Error

components:
  responses:
    ValidationError:
      description: "Validation error."
      content:
        application/json:
          schema:
            type: "object"
            properties:
              detail:
                type: "array"
                items:
                  type: "object"
                  properties:
                    loc:
                      type: "array"
                      items:
                        type: "string"
                        minLength: 1
                    message:
                      type: "string"
                      minLength: 1
                  required: ["loc", "message"]
            required: ["detail"]

Custom Error Handling

In case if aiohttp.web application doesn’t want or cannot use described way of handling errors via aiohttp_middlewares.error.error_middleware(), it needs to disable error middleware usage entirely by passing use_error_middleware=False on setting up OpenAPI support,

from pathlib import Path

from aiohttp import web
from rororo import setup_openapi


app = setup_openapi(
    web.Application(),
    Path(__file__).parent / "openapi.yaml",
    operations,
    use_error_middleware=False,
)

In that case aiohttp.web application need to implement its own way of handling OpenAPI (and other) errors.