How do one add a description to a request body?

[venkat5554]

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()

@app.post("/items")
async def create_item(item: Item = Body(description="new")):
    return {"item": item.dict()}

Description

The api doc should normally allocate the description to the request body, however it does not.

Operating System

Windows

Operating System Details

No response

FastAPI Version

fastapi==0.91.0

Python Version

3.11.1

Additional Context

[clemens-tolboom]

I just watch https://youtu.be/SORiTsvnU28?t=1149 where I learned the annotation is the place to document

# Create a API endpoint
@app.get("/api",
    description="This is a description of the API endpoint",
    responses={
        200: { "description": "We definitely need some data from you", }
})

[venkat5554]

It doesn't answer my question

[clemens-tolboom]

Nice. How do you change the status to Answered?

I misread the question.

[williamjamir]

I think (please, anyone correct me if I'm wrong) you can't do this without customization.

By default, any extra key sent to the Body field is registered as a custom field for the schema.
Link to the docs -> https://fastapi.tiangolo.com/tutorial/body-fields/#add-extra-information

But if I understand correctly, in your case, you want to populate the requestBody.description section from the openAPI spec. However, the generated JSON assigns this key (in your example description) as requestBody.content.application/json.schema.<key name>'.

You can check this in the source code here:
https://github.com/tiangolo/fastapi/blob/master/fastapi/openapi/utils.py#L141

An alternative solution is to customize the openapi with a function custom_openapi like the example below:

Note in the example below that I'm accessing the openapi_schema object explicitly (with a lot of chained dict access) to make the path clear and my example easy to understand 😅

from fastapi import FastAPI, Body
from fastapi.openapi.utils import get_openapi
from pydantic import BaseModel


class Item(BaseModel):
    """
    Docstring from Pydantic
    """

    basename: str


app = FastAPI()


@app.post("/items")
async def create_item(item: Item = Body(description="Body Description")):
    """Endpoint description"""
    return {"item": item.dict()}




def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(title="", version="", routes=app.routes    )
    original_docstring = openapi_schema["paths"]["/items"]["post"]["requestBody"]["content"]["application/json"]["schema"]["description"]
    openapi_schema["paths"]["/items"]["post"]["requestBody"]["description"] = original_docstring
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

if __name__ == "__main__":
    import uvicorn

    uvicorn.run("x:app", reload=False)

Does this answer your question?

[Ryandaydev]

I haven't figured out a solution different than the one @williamjamir has above. But just to point out one thing that may cause some confusion, it appears to me that the example Swagger UI that @clemens-tolboom shared is using OpenAPI 2.x (or Swagger).

I am basing this on the fact that the screenshot shows the body as a parameter, and the description as a parameter description. FastAPI current version generates an OpenAPI 3.x, in which the requestBody replaced the body as a parameter.

Here's info on that change:
https://swagger.io/docs/specification/describing-request-body/

You can see this difference if you look at the petstore example and look at the /pet endpoint put verb:

2.x here (body is a parameter):
https://petstore.swagger.io/

And compare to the 3.x here (uses requestBody):
https://editor.swagger.io/?docExpansion=none

Note: here's the issue that states FastAPI doesn't support OpenAPI 2.x
#70

[YuriiMotov]

The correct way to specify description for request body is to use openapi_extra={"requestBody": {"description": "Request body description"}}:

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str


@app.post(
    "/items",
    openapi_extra={"requestBody": {"description": "Request body description"}},
)
async def create_item(item: Item = Body()):
    pass

FastAPI doesn't take description from Body(description="...") because there might be multiple body parameters in your endpoint:

@app.post("/items")
async def create_item(
    item: Item = Body(description="Description 1"),
    something: AnotherModel = Body(description="Description 2"),
):
    pass