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 Response(data=Data(state="ok"))

# 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 Response(data=Data(state="ok"))

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

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

Description

Problem

When generating the OpenAPI JSON via app.openapi(), FastAPI internally remaps $ref names.

Identical model names (Data, Response) across routers are remapped non-deterministically, resulting in inconsistent OpenAPI JSON between runs.

Example:

{'$ref': '#/components/schemas/routers__one__Response'},
{'$ref': '#/components/schemas/routers__two__Response'},
{'$ref': '#/components/schemas/Data'}

Depending on the run, Data may be mapped to routers__one__Data or routers__two__Data, breaking CI checks.

Attempts

I’ve tried adding docstrings to models to disambiguate names.

Sorting router inclusion order doesn’t help.

Manually renaming models per router works but is cumbersome in large projects.

Question

Is this non-deterministic behavior expected in FastAPI v0.121+ when generating OpenAPI for multiple routers with identically named models?

Are there recommended best practices for multi-router projects to avoid $ref collisions without manually renaming every model?

Would it make sense for FastAPI to implement a deterministic $ref remapping internally to avoid CI flakiness?

Any insights or suggestions would be appreciated!

Thank you 🙏

Operating System

Windows

Operating System Details

No response

FastAPI Version

python -c "import fastapi; print(fastapi.version)"

Pydantic Version

python -c "import pydantic; print(pydantic.version.VERSION)"

Python Version

python --version

Additional Context

No response