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

# routers/one.py
from fastapi import APIRouter
from pydantic import BaseModel

router = APIRouter(prefix="/one")

class Data(BaseModel):
    state: str

class Response(BaseModel):
    data: Data

@router.get("", response_model=Response)
def get_one():
    return {"data": {"state": "one"}}

# routers/two.py
from fastapi import APIRouter
from pydantic import BaseModel

router = APIRouter(prefix="/two")

class Data(BaseModel):
    state: str

class Response(BaseModel):
    data: Data

@router.get("", response_model=Response)
def get_two():
    return {"data": {"state": "two"}}

# main.py
from fastapi import FastAPI
from routers import one, two

app = FastAPI()
app.include_router(one.router)
app.include_router(two.router)

Description

I am generating the OpenAPI schema using app.openapi() and noticed that models with the same name in different routers (like Data and Response) sometimes generate duplicate $ref entries.

Sometimes #/components/schemas/Data is remapped to routers__one__Data or routers__two__Data nondeterministically.

This causes CI checks on the OpenAPI schema to fail intermittently.

Adding docstrings or renaming the models works as a workaround, but it’s not ideal.

Is there a recommended way to prevent FastAPI from generating nondeterministic $ref names when multiple routers use models with the same name?

Operating System

Windows

Operating System Details

No response

FastAPI Version

FastAPI Version: 0.121.x

Pydantic Version

Pydantic Version: 2.x

Python Version

Python Version: 3.11+

Additional Context

I want to reliably generate OpenAPI schemas for CI testing and code generation, without manually renaming models for every router.