How to display many to many relationships in swagger after using type_checking

[lionjiadong]

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 SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" 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 SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from fastapi import APIRouter, Query, Request
from sqlmodel import select
from src.database.core import SessionDep
from src.test.models.team import TeamOut, Team, TeamBase

team_router = APIRouter(
    prefix="/team",
    tags=["team"],
)


@team_router.get("/", response_model=list[TeamOut])
async def read_teams(
    request: Request,
    session: SessionDep,
    offset: int = 0,
    limit: int = Query(default=100, le=100),
):
    teams = (await session.exec(select(Team).offset(offset).limit(limit))).all()
    return teams

Description

This is my directory structure

.
├── test
    ├── __init__.py
    ├── models
        ├── hero.py
        ├── team.py
        ├── links.py
    ├── routers
        ├── hero.py
        ├── team.py
├── main.py

models/hero.py

from typing import TYPE_CHECKING
from sqlmodel import Field, Relationship, SQLModel
from .links import HeroTeamLink

if TYPE_CHECKING:
    from .team import Team

class HeroBase(SQLModel):
    name: str

class HeroOut(HeroBase):
    teams: list["Team"] = []

class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str = Field(index=True)

    teams: list["Team"] = Relationship(back_populates="heroes", link_model=HeroTeamLink)

models/team.py

from typing import TYPE_CHECKING
from sqlmodel import Field, Relationship, SQLModel
from .links import HeroTeamLink

if TYPE_CHECKING:
    from .hero import Hero

class TeamBase(SQLModel):
    name: str

class TeamOut(TeamBase):
    heroes: list["Hero"] = []

class Team(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str = Field(index=True)

    heroes: list["Hero"] = Relationship(back_populates="teams", link_model=HeroTeamLink)

models/links.py

from sqlmodel import Field, SQLModel

class HeroTeamLink(SQLModel, table=True):
    team_id: int | None = Field(default=None, foreign_key="team.id", primary_key=True)
    hero_id: int | None = Field(default=None, foreign_key="hero.id", primary_key=True)

routers/hero.py

from fastapi import APIRouter, Query, Request
from sqlmodel import select
from src.database.core import SessionDep
from src.test.models.hero import HeroOut, Hero, HeroBase

hero_router = APIRouter(
    prefix="/hero",
    tags=["hero"],
)

@hero_router.get("/", response_model=list[HeroOut])
async def read_heros(
    session: SessionDep,
    offset: int = 0,
    limit: int = Query(default=100, le=100),
):
    heros = (await session.exec(select(Hero).offset(offset).limit(limit))).all()
    return heros

routers/team.py

from fastapi import APIRouter, Query, Request
from sqlmodel import select
from src.database.core import SessionDep
from src.test.models.team import TeamOut, Team, TeamBase

team_router = APIRouter(
    prefix="/team",
    tags=["team"],
)

@team_router.get("/", response_model=list[TeamOut])
async def read_teams(
    request: Request,
    session: SessionDep,
    offset: int = 0,
    limit: int = Query(default=100, le=100),
):
    teams = (await session.exec(select(Team).offset(offset).limit(limit))).all()
    return teams

When I run and access http://127.0.0.1:8000/docs# ， I got this：

console got this：

Traceback (most recent call last):
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/uvicorn/protocols/http/httptools_impl.py", line 409, in run_asgi
    result = await app(  # type: ignore[func-returns-value]
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        self.scope, self.receive, self.send
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/uvicorn/middleware/proxy_headers.py", line 60, in __call__
    return await self.app(scope, receive, send)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/fastapi/applications.py", line 1054, in __call__
    await super().__call__(scope, receive, send)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/applications.py", line 112, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/middleware/errors.py", line 187, in __call__
    raise exc
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/middleware/errors.py", line 165, in __call__
    await self.app(scope, receive, _send)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/middleware/cors.py", line 85, in __call__
    await self.app(scope, receive, send)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/middleware/exceptions.py", line 62, in __call__
    await wrap_app_handling_exceptions(self.app, conn)(scope, receive, send)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/_exception_handler.py", line 53, in wrapped_app
    raise exc
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/routing.py", line 714, in __call__
    await self.middleware_stack(scope, receive, send)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/routing.py", line 734, in app
    await route.handle(scope, receive, send)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/routing.py", line 288, in handle
    await self.app(scope, receive, send)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/routing.py", line 76, in app
    await wrap_app_handling_exceptions(app, request)(scope, receive, send)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/_exception_handler.py", line 53, in wrapped_app
    raise exc
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/_exception_handler.py", line 42, in wrapped_app
    await app(scope, receive, sender)
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/starlette/routing.py", line 73, in app
    response = await f(request)
               ^^^^^^^^^^^^^^^^
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/fastapi/applications.py", line 1009, in openapi
    return JSONResponse(self.openapi())
                        ~~~~~~~~~~~~^^
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/fastapi/applications.py", line 981, in openapi
    self.openapi_schema = get_openapi(
                          ~~~~~~~~~~~^
        title=self.title,
        ^^^^^^^^^^^^^^^^^
    ...<11 lines>...
        separate_input_output_schemas=self.separate_input_output_schemas,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/fastapi/openapi/utils.py", line 514, in get_openapi
    field_mapping, definitions = get_definitions(
                                 ~~~~~~~~~~~~~~~^
        fields=all_fields,
        ^^^^^^^^^^^^^^^^^^
    ...<2 lines>...
        separate_input_output_schemas=separate_input_output_schemas,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/fastapi/_compat.py", line 232, in get_definitions
    field_mapping, definitions = schema_generator.generate_definitions(
                                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        inputs=inputs
        ^^^^^^^^^^^^^
    )
    ^
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 363, in generate_definitions
    self.generate_inner(schema)
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/pydantic/json_schema.py", line 443, in generate_inner
    if 'ref' in schema:
       ^^^^^^^^^^^^^^^
  File "/home/lk/.pyenv/versions/3.13.5/lib/python3.13/_collections_abc.py", line 817, in __contains__
    self[key]
    ~~~~^^^^^
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/pydantic/_internal/_mock_val_ser.py", line 41, in __getitem__
    return self._get_built().__getitem__(key)
           ~~~~~~~~~~~~~~~^^
  File "/home/lk/code/fastapi-demo/.venv/lib/python3.13/site-packages/pydantic/_internal/_mock_val_ser.py", line 58, in _get_built
    raise PydanticUserError(self._error_message, code=self._code)
pydantic.errors.PydanticUserError: `TypeAdapter[typing.Annotated[list[src.test.models.team.TeamOut], FieldInfo(annotation=list[TeamOut], required=True)]]` is not fully defined; you should define `typing.Annotated[list[src.test.models.team.TeamOut], FieldInfo(annotation=list[TeamOut], required=True)]` and all referenced types, then call `.rebuild()` on the instance.

For further information visit https://errors.pydantic.dev/2.11/u/class-not-fully-defined

How to implement nested response_model after applying the official loop pouring solution
https://sqlmodel.tiangolo.com/tutorial/code-structure/

Operating System

macOS

Operating System Details

No response

SQLModel Version

0.0.24

Python Version

Python 3.13.5

Additional Context

No response

[YuriiMotov]

You need to rebuild models.
Simple way is to add the following to models/__init__.py:

from .hero import Hero, HeroBase, HeroOut  # noqa: F401
from .team import Team, TeamBase, TeamOut  # noqa: F401

HeroOut.model_rebuild()
TeamOut.model_rebuild()

[lionjiadong]

thanks！