Add additional object schemas to generated documentation to describe webhook responses

[jfeaver]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question 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()


class Score(BaseModel):
    """This schema is used in a post-processing webhook and is not required by the API but is useful to API consumers to see in the documentation."""

    id: str
    score: int

class EducationScoresSchema(BaseModel):
    """Required form data to request scoring."""

    webhook_url: Annotated[
        str,
        Form(
            description=(
                "The webhook URL provided by you where we'll send the results. A POST request will be made to this URL with a JSON body containing a list of `Score` objects."
            )
        ),
    ]
    # more stuff in the request body but abridged here.

def to_reference_object(pydantic_model):
    # needs an implementation

# Using `openapi_extra` to describe additional parameters is the closest thing to a solution I can figure out. Is it the right way to go? I'm not sure.
@app.post(
    "/scores",
    response_class=JSONResponse,
    openapi_extra={"parameters": [to_reference_object(score)]}
)
async def score_student_responses(
    data: Annotated[EducationScoresSchema, Form()],
) -> JSONResponse:
    # do stuff. End with a simple 200 response. Asynchronously and Later on a webhook request will be sent out.

Description

I've got some objects that are used by my API outside of the usual request/response cycle because we send webhook responses. How can I add reference schemas to the generated openapi json schema so that my API consumers can easily see what kind of response they'll receive in the webhook?

Operating System

macOS

Operating System Details

No response

FastAPI Version

0.115.0

Pydantic Version

2.9.2

Python Version

3.12.3

Additional Context

No response

[jfeaver]

After posting I found that FastAPI provides a documentation solution specifically for webhooks and it is probably a better solution compared to adding reference objects to the schema.

Here's the documentation about add webhook documentation: https://fastapi.tiangolo.com/advanced/openapi-webhooks/.