Include possible HTTPExceptions in OpenAPI spec

[onecrayon]

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.
• After submitting this, I commit to one of:
  • Read open issues with questions until I find 2 issues where I can help someone and add a comment to help there.
  • I already hit the "watch" button in this repository to receive notifications and I commit to help at least 2 people that ask questions in the future.
  • Implement a Pull Request for a confirmed bug.

Example

Here's a self-contained, minimal, reproducible, example with my use case:

from fastapi import FastAPI, HTTPException

app = FastAPI()


@app.get("/")
def read_root(gimme_coffee: bool = False):
    if gimme_coffee:
        raise HTTPException(status_code=418, detail="I'm a teapot.")
    return {"Hello": "World"}

Description

• Open the browser and call the endpoint /docs
• Note that the only listed response codes are 200 and 422
• Execute the route with gimme_coffee set to true and note that it returns a 418 status code

How do I set the status code for 418 in the OpenAPI docs? I was expecting to be able to pass in a list of possible HTTPExceptions and have them be automatically converted, but there does not appear to be any way to do that. The closest thing I found was Additional Status Codes but that seemed at best tangentially relevant since I am raising HTTPExceptions, not looking to build out a custom exception JSON response.

Properly documenting error states is just as important as documenting the success state. I really hope FastAPI provides an easy way to do this.

Environment

• OS: Linux (Docker container using standard python-3.8 image)
• FastAPI Version: 0.61.1
• Python version: 3.8.5

[ycd]

Yes, you can declare additional responses with additional status codes etc. You just need to add it as a path parameter then those additional responses will be included in the OpenAPI schema, here is a example

@app.get("/",responses={418: {"detail": "I'm a teapot"}, 413: {"Too large": "...The Payload"}})
def read_root(gimme_coffee: bool = False):
    if gimme_coffee:
        raise HTTPException(status_code=418, detail="I'm a teapot.")
    return {"Hello": "World"}

Documentation for Additional Responses

[onecrayon]

That's the additional status codes I mentioned above, and it is a long way from easy. I was hoping I could instantiate an error, pass it in similar to response_model and have the OpenAPI generation just do the right thing, but looks like I would need to basically duplicate the entire error into the decorator.

Nuts. I guess this is actually a feature request: we need a better way to handle error message documentation. My preference would be to just pass in a list of some base error classes and have it figure out the status code and output formatting based on that (having the actual error output isn't necessary, particularly since it may well change depending on the situation). That way, I could setup a sub-class of HTTPException that defaults to a 418 status code, and by passing that in and using it my exception is fully documented.

[David-Lor]

@onecrayon On my APIs I'm using custom exceptions that include references to the error code, message and Pydantic model to be returned. I have an example over here: https://github.com/David-Lor/FastAPI-Pydantic-Mongo_Sample_CRUD_API

On a nutshell:

• I create the custom exceptions (https://github.com/David-Lor/FastAPI-Pydantic-Mongo_Sample_CRUD_API/blob/master/people_api/exceptions.py)
• I create the models for exception responses (https://github.com/David-Lor/FastAPI-Pydantic-Mongo_Sample_CRUD_API/blob/master/people_api/models/errors.py)
• On the routes, I call a function that creates the "responses" dict, given multiple custom exceptions (https://github.com/David-Lor/FastAPI-Pydantic-Mongo_Sample_CRUD_API/blob/master/people_api/app.py)
• I use a request middleware, where a try/except can catch my custom exceptions, and return their custom response, based on the exception status code, message and model (https://github.com/David-Lor/FastAPI-Pydantic-Mongo_Sample_CRUD_API/blob/master/people_api/middlewares.py)

Probably far from ideal and might be better ways to achieve it, but for now it's been working pretty fine for me. It's more complex though.

[ycd]

@onecrayon Does something like this would work for you?`

from fastapi import FastAPI, APIRouter


app = FastAPI()
router = APIRouter()


@router.get("/dummy1")
async def dummy1():
    ...


@router.get("/dummy2")
async def dummy2():
    ...


@router.get("/dummy3")
async def dummy3():
    ...


@router.get("/dummy4")
async def dummy4():
    ...


app.include_router(
    router,
    responses={
        418: {
            "description": "I'm a teapot",
            "content": {"application/json": {"example": {"dummy": "dumdum"}}},
        },
        413: {
            "description": "I'm too large",
            "content": {"application/json": {"example": {"dummy": "dumdum"}}},
        },
    },
)

[onecrayon]

@ycd Per my comment here, that's what I'm doing. It's also unnecessary code duplication. My feature request is for an easy way to pass in children of HTTPException and just have FastAPI automatically figure out what the error output should look like. So for example here's some pseudo-code that's based on my current project:

from fastapi import status, HTTPException

class APIException(HTTPException):
    """Light wrapper around HTTPException that allows specifying defaults via class property"""

    status_code = status.HTTP_400_BAD_REQUEST
    detail = None
    headers = None

    def __init__(self, *args, **kwargs):
        if "status_code" not in kwargs:
            kwargs["status_code"] = self.status_code
        if "detail" not in kwargs:
            kwargs["detail"] = self.detail
        if "headers" not in kwargs:
            kwargs["headers"] = self.headers
        super().__init__(*args, **kwargs)

class TeapotException(APIException):
    status_code = 418
    detail = "I'm a teapot."

@app.get("/")
def read_root(gimme_coffee: bool = False, response_exceptions=[TeapotException]):
    if gimme_coffee:
        raise TeapotException()
    return {"Hello": "World"}

Even better would be to have FastAPI able to introspect the method and look for HTTPException-derived exceptions to auto-populate the list, but that's possibly edging a little too far into magical territory.

In any case, it's silly that I can have FastAPI automatically discover query params and such based on passed classes, but need to explicitly duplicate all of the information that's already stored in my exception classes in order to document exceptions.

[skaanbilly2]

Is this issue on the planning, or can I create a PR for this?

[Kludex]

Does this helps? https://github.com/Kludex/fastapi-responses

[onecrayon]

@Kludex That is exactly the sort of thing that I'm looking for! Granted, it's a little more "magical" than I usually like, but I would happily take it over the current setup where I have to explicitly define status codes and error strings multiple times.

[jtv8]

@onecrayon - given that the main use case for this is setting some expectations for API users on what HTTP responses to handle, would this suffice?

@app.get("/", response_exceptions=[418])
def read_root(gimme_coffee: bool = False):
    if gimme_coffee:
        raise HTTPException(status_code=418, detail="I'm a teapot.")
    return {"Hello": "World"}

[onecrayon]

@jtv8 No, that's insufficient. The API spec needs to be able to output not only the status code, but also the specification for the response body (since different exceptions often have different JSON body responses that get rendered, or other methods for reporting what went wrong).

[aiguofer]

+1 here. I'm currently designing various exceptions, each having a slightly different response payloads. I would love to have a convenient way to specify those different exceptions in our swagger docs. I like @onecrayon's example usage... it seems pretty consistent with existing FastAPI paradigms. However, in my case I'm also modifying the payload, so I'm not sure how that could be handled.

In my case:

class SessionConflictException(HTTPException):
    def __init__(self, session_id) -> None:
        self.session_id = session_id
        super().__init__(
            status_code=status.HTTP_409_CONFLICT,
            detail="Conflict: Session already exists and has not been terminated",
        )

@app.exception_handler(SessionConflictException)
async def session_conflict_exception_handler(
    request: Request, exc: SessionConflictException
):
    return JSONResponse(
        content=jsonable_encoder({"detail": exc.detail, "session_id": exc.session_id}),
        status_code=exc.status_code,
    )

I feel like this could be achieved somehow combining a pydantic BaseModel and a fastapi HTTPException into some sort of base class, with the only requirement being that it must contain a valid status_code.

[thedmdim]

Any update here?

[leehanchung]

Bump. In the absence of any decisions, what is the proper pattern for documenting the HTTPExceptions?

[jackirvine97]

Have there been any advancements on most DRY compliant pattern for ensuring custom HTTPExceptions are displayed in OpenAPI docs?

[JoakimJoensuu]

What I would like to see is using Pydantic model to define contents of error response body.

In my case I have client and server that share common library which contains all request and response bodies defined as Pydantic models. This helps in interpreting req&resp bodies on both sides.

[yovelcohen]

Just for anyone passing by, here's how I'm handling it, I don't think it's ideal, but does the trick.
It creates a pydantic model dynamically with the given message and error_name.
you can create any error, but since I have a lot of crud APIs I chose to add the two extra utilities that create error by passing on the original response model your endpoint returns.

def APIExcpetion(error_name, msg):
    error_name += 'Error'
    return create_model(error_name, detail=(str, msg))

def ObjNotFoundError(obj: Type[BaseModel], lookup_field=None):
    name = obj.__name__
    msg = f'{name} with {lookup_field} not found' if lookup_field else f'{name} not found'
    return APIExcpetion('NotFound', msg)

def ObjExistError(obj, lookup_field=None):
    name= obj.__name__
    msg = f'{name} with {lookup_field} already exists' if lookup_field else f'{name} already exists'
    return APIExcpetion('ObjectExist', msg)

Example Usage:

@router.post(
    '/{client_id}/channels',
    response_model=ClientChannel,
    responses={404: {'model': ObjNotFoundError(Client, 'id')},
               400: {'model': ObjExistError(ClientChannel, 'name')}}
)
async def create_channel(
        user: Annotated[User, Depends(get_current_glix_user)],
        client_id: PydanticObjectId,
        channel_form: ClientChannelForm
) -> ClientChannel:
    """
    Create a new channel for a client
    """
    # I'm using Beanie, so this is just some pseudo functions to get your models...
    client, channel_exist = await asyncio.gather(get_client(client_id), check_channel_exists(client_id,channel_form.name))
    if not client:
        raise HTTPException(status_code=404, detail='Client not found')
    if channel_exist:
        raise HTTPException(status_code=400, detail='Channel with this name and client already exists')
    # do stuff and return model...

[jeremyschiemann]

+1

For me it would be enough to have extra responses coupled to a dependency, so that when an endpoint is using the dependency, it automatically adds the response to it. (see #11144)

[estebanx64]

Hi there.

As many others have mentioned, the only way so far is following this section from the doc additional-responses

or even including the responses at a router level.

app.include_router(
    router,
    responses={
        418: {
            "description": "I'm a teapot",
            "content": {"application/json": {"example": {"dummy": "dumdum"}}},
        },
        413: {
            "description": "I'm too large",
            "content": {"application/json": {"example": {"dummy": "dumdum"}}},
        },
    },
)

I'm marking this question as answered and labeling as possible feature. We don't have any due date or whether is gonna be included or not yet

[PlugNPush]

Correct me if I am wrong, but out of all the attempts described here, there is no way to properly document two identical HTTP status codes with different "example" messages?

[Rey092]

Correct me if I am wrong, but out of all the attempts described here, there is no way to properly document two identical HTTP status codes with different "example" messages?

or just use "examples": [] instead of "example": {}

[Rey092]

https://pypi.org/project/fastapi_errors/
you can try my package. multiple examples for one error code is supported
builded it in a few hours so be careful or just copy paste source to update by yourself if needed