Faulty OpenApi spec for nested model + multiple responses

[jadeidev]

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, Response
app = FastAPI()

class ModelA(BaseModel):
    name: str

class ModelB(BaseModel):
    nameA: ModelA

class ModelC(BaseModel):
    nameB: ModelB

@app.post("/", status_code=201,
          responses={208: {"description": "Already exists",
                           "model": ModelC}},
          )
def post_root(response: Response) -> ModelC:
    if True:  # for example if already exists
        response.status_code = 208
        return ModelC(nameB=ModelB(nameA=ModelA(name="name")))
    else:
        # create
        return ModelC(nameB=ModelB(nameA=ModelA(name="name")))

uvicorn.run(app, host="localhost", port=8000)

Description

probelm

When a model is nested with 2 levels or more and there are multiple responses faulty OpenApi schema is generated:
a redundant ModelC-Input and ModelC-Output are generated instead of just one ModelC

openapi: "3.1.0"
info: 
  title: "FastAPI"
  version: "0.1.0"
paths: 
  /: 
    post: 
      summary: "Post Root"
      operationId: "post_root_A_post"
      responses: 
        201: 
          description: "Successful Response"
          content: 
            application/json: 
              schema: 
                $ref: "#/components/schemas/ModelC-Output"
        208: 
          description: "Already exists"
          content: 
            application/json: 
              schema: 
                $ref: "#/components/schemas/ModelC-Input"
components: 
  schemas: 
    ModelA: 
      properties: 
        name: 
          type: "string"
          title: "Name"
      type: "object"
      required: 
      - "name"
      title: "ModelA"
    ModelB: 
      properties: 
        nameA: 
          $ref: "#/components/schemas/ModelA"
      type: "object"
      required: 
      - "nameA"
      title: "ModelB"
    ModelC-Input: 
      properties: 
        nameB: 
          $ref: "#/components/schemas/ModelB"
      type: "object"
      required: 
      - "nameB"
      title: "ModelC"
    ModelC-Output: 
      properties: 
        nameB: 
          $ref: "#/components/schemas/ModelB"
      type: "object"
      required: 
      - "nameB"
      title: "ModelC"

other test cases

if model is nested 2 level but with single response the result is correct :

from fastapi import FastAPI, Response
app = FastAPI()

class ModelA(BaseModel):
    name: str

class ModelB(BaseModel):
    nameA: ModelA

class ModelC(BaseModel):
    nameB: ModelB

@app.post("/", status_code=201)
def post_root_single(response: Response) -> ModelC:
    return ModelC(nameB=ModelB(nameA=ModelA(name="name")))
uvicorn.run(app, host="localhost", port=8000)

the resulting model is correct (ie only ModelC created):

openapi: "3.1.0"
info: 
  title: "FastAPI"
  version: "0.1.0"
paths: 
  /: 
    post: 
      summary: "Post Root Single"
      operationId: "post_root_single__post"
      responses: 
        201: 
          description: "Successful Response"
          content: 
            application/json: 
              schema: 
                $ref: "#/components/schemas/ModelC"
components: 
  schemas: 
    ModelA: 
      properties: 
        name: 
          type: "string"
          title: "Name"
      type: "object"
      required: 
      - "name"
      title: "ModelA"
    ModelB: 
      properties: 
        nameA: 
          $ref: "#/components/schemas/ModelA"
      type: "object"
      required: 
      - "nameA"
      title: "ModelB"
    ModelC: 
      properties: 
        nameB: 
          $ref: "#/components/schemas/ModelB"
      type: "object"
      required: 
      - "nameB"
      title: "ModelC"

if model is nested only 1 level with 2 responses the result is correct:

from fastapi import FastAPI, Response
app = FastAPI()

class Model1(BaseModel):
    name: str

class Model2(BaseModel):
    name1: Model1

@app.post("/", status_code=201, response_model=Model2,
          responses={208: {"description": "Already exists",
                           "model": Model2}},
          )
def post_root_1(response: Response) -> Model2:
    if True:  # for example if already exists
        response.status_code = 208
        return Model2(name1=Model1(name="name"))
    else:
        # create
        return Model2(name1=Model1(name="name"))


uvicorn.run(app, host="localhost", port=8000)

resulting model is correct:

openapi: "3.1.0"
info: 
  title: "FastAPI"
  version: "0.1.0"
paths: 
  /: 
    post: 
      summary: "Post Root 1"
      operationId: "post_root_1_1_post"
      responses: 
        201: 
          description: "Successful Response"
          content: 
            application/json: 
              schema: 
                $ref: "#/components/schemas/Model2"
        208: 
          description: "Already exists"
          content: 
            application/json: 
              schema: 
                $ref: "#/components/schemas/Model2"
components: 
  schemas: 
    Model1: 
      properties: 
        name: 
          type: "string"
          title: "Name"
      type: "object"
      required: 
      - "name"
      title: "Model1"
    Model2: 
      properties: 
        name1: 
          $ref: "#/components/schemas/Model1"
      type: "object"
      required: 
      - "name1"
      title: "Model2"

Operating System

Linux

Operating System Details

any OS

FastAPI Version

0.111.0

Pydantic Version

2.7.4

Python Version

3.12.3

Additional Context

No response