Show only top-level models in the docs

[KDruzhkin]

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 pydantic import BaseModel
from fastapi import FastAPI


class _X(BaseModel):
    x: int


class _Y(BaseModel):
    y: int
    x_model: _X


class Z(BaseModel):
    z: int
    y_model: _Y


app = FastAPI()


@app.get("/")
def read_root(z_model: Z) -> int:
    return 0

Description

I am looking at the auto-generated docs page http://127.0.0.1:8000/docs, section “Schemas”. It shows not only the main model Z, but also auxiliary models _Y and _X. How do I hide them?

Note that the schemas of _Y and _X are perfectly visible inside the definition of Z. I only want to hide their names, and to shorten the list of schemas.

Operating System

macOS

Operating System Details

No response

FastAPI Version

0.111.1

Pydantic Version

2.8.2

Python Version

3.12

Additional Context

[AIdjis]

Hello, if you want to hide models from the schema documentation, you might need to manually create a custom OpenAPI schema to hide them, just like the example below:

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



class _X(BaseModel):
    x: int


class _Y(BaseModel):
    y: int
    x_model: _X


class Z(BaseModel):
    z: int
    y_model: _Y


app = FastAPI()


@app.get("/")
def read_root(z_model: Z) -> int:
    return 0

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="My API",
        version="1",
        routes=app.routes,
    )
    # Remove auxiliary models from the schema
    openapi_schema["components"]["schemas"].pop("_X", None)
    openapi_schema["components"]["schemas"].pop("_Y", None)
    app.openapi_schema = openapi_schema
    return app.openapi_schema
app.openapi = custom_openapi

You might encounter an error in the documentation related to the OpenAPI schema. It still references the _Y and _X models in the Z model, even though they have been removed from the schemas. just ignore it.

Remember, this technique only removes the models from the documentation. You still need to ensure that the data is properly sent to your API for it to function correctly.

[KDruzhkin]

It works, but the error is shown above, as you expected.

[AIdjis]

I mentioned that you can ignore this error. I've tested the endpoint, and it works correctly. You just need to ensure that you send the JSON data properly. This is the perfect solution to your question. FastAPI requires that schemas adhere strictly to the schema definitions provided in the code. To address this, you need to set up custom schema documentation.