Registering a common error model for Swagger

[rustam-ashurov-mcx]

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from fastapi import FastAPI

app = FastAPI()


@app.get("/mangos")
async def root():
    raise Exception("We have no mangos")

@app.get("/bananas")
async def root():
    raise Exception("We have no bananas")

Description

My situations:

• I have a standard error response model (let's say ErrorResponseV1) for all error status code responses in RestAPI application
• Being more details, having custom middleware I'm able to map all exceptions including built-in validation and not found exceptions on the previously mentioned ErrorResponseV1 format
• Now I would like to use swagger UI. therefore it would be great to have a mechanism to let FastApi know that in case of 404, 409, 400 responses from server we use ErrorResponseV1 model

However by default:

• FastApi has no idea that my middleware handling all exceptions and return ErrorResponseV1
• FastApi still annotates some endpoints with ibuilt-in error models formats which is misleading. E.g. sometimes FastApi says that an endpoint is able to return 422 response with ValidationError model
• Plus at the bottom of Swagger UI page there are some built-in error response models like HTTPValidationError and previously mentioned ValidationError

I don't want to manually craft Swagger schema from 0, and I even like when FastApi tries to predict possible response statuses based on endpoint parameters.
I tried to use the "responses" parameter in FastApi app constructor or when I'm adding a router, but firstly it does not work with a Type parameter making things complicated.
I tried to pass a schema getting it via Pydantic schema() method since my error model inherits BaseModel, but it looks like it doesn't work and requires manual crafting and adjusting.

Even when it's done with manual schema writing and passing it via "responses", FastApi applies all registered responses on all endpoints.
E.g. In case of usage:
FastAPI(responses = {422 : {...schema...}})
FastApi will add this type of response to all endpoints in the app.

Therefore I just want to know whether I can let FastApi know which model to expect as a default one in case of errors. It could one for all errors or per Http Error code type. And expected output is straightforward:

• FastApi still tries to predict possible http responses but using my model
• There are no built-in error response models in swagger (bth, this one I can deal with, can just delete these models from generated schema knowing that no endpoint documentation in swagger will refer to it anymore)

Many thanks :)

Operating System

Linux

Operating System Details

No response

FastAPI Version

0.75.2

Python Version

3.9.5

Additional Context

No response

[zoliknemet]

1. Try to use exception_handler, not middleware for exception handling

@app.exception_handler(ExceptionNotFound)
async def http_exception_handler(request, exc):
    return JSONResponse(status_code=404, content={"message": str(exc)})

2. Fastapi does not support automatic generation of responses other than ValueError (pydantic raises that), but you can always separate APIRouter and define responses only on certain endpoints that are in that router

FULL EXAMPLE:

import uvicorn as uvicorn

from fastapi import FastAPI, APIRouter
from fastapi.responses import JSONResponse

app = FastAPI()


class ExceptionNotFound(Exception):
    pass


class ExceptionConflict(Exception):
    pass


@app.exception_handler(ExceptionNotFound)
async def http_exception_handler(request, exc):
    return JSONResponse(status_code=404, content={"message": str(exc)})


@app.exception_handler(ExceptionConflict)
async def http_exception_handler(request, exc):
    return JSONResponse(status_code=409, content={"message": str(exc)})


fruit_router = APIRouter(
    responses={
        404: {"description": "Not found"},
        409: {"description": "Conflict in data"},
    }
)


@app.get("/pure-responses")
async def pure_responses():
    raise ExceptionNotFound("Pure responses not found exception!")


@fruit_router.get("/mangos")
async def mangos():
    raise ExceptionNotFound("We have no mangos")


@fruit_router.get("/bananas", responses={419: {"description": "We have conflict"}})
async def bananas():
    raise ExceptionConflict("We have no bananas")


app.include_router(fruit_router)

/mangos and /bananas are part of fruit_router which has defined respones:

fruit_router = APIRouter(
    responses={
        404: {"description": "Not found"},
        409: {"description": "Conflict in data"},
    }
)

/bananas endpoint in example has extra response 419

/pure-responses does not have 404 and 409 defined, but exception_handlers are defined on whole APP

screenshot of /docs

NOTE: divide different APIRouters in different files