Add option to create openapi 3.0 links for generated schemas

[astronuttt]

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue 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
from pydantic import BaseModel


class CreateSubItem(BaseModel):
    id: int
    name: str


class CreateItem(BaseModel):
    id: int
    name: str
    sub_item_id: int


app = FastAPI()


@app.post("/subitem/")
async def create_sub_item(subitem: CreateSubItem):
    ...


@app.post("/item")
async def create_item(item: CreateItem):
    ...

Description

with OpenAPI 3.0 links, we can describe how various values returned by one operation can be used as input for other operations as described here.

I checked the documentation and GitHub issues but couldn't find anything related to this.

so in the code example i provided, we could get the returned CreateSubItem.id for the next request when we create an Item as CreateItem.sub_item_id.

Wanted Solution

It would be great if we could define these kinds of links somehow in the Pydantic models or any other way.

I'm sure there is a better way to implement this, but my suggestion is to define the relationship as a string to the Pydantic model. maybe as an extra keyword argument value to the Pydantic's Field.

for example Field(..., refrences="SomeModel.id") and FastAPI pickup that and create that refrence in schema generation.

Wanted Code

from fastapi import FastAPI
from pydantic import BaseModel


class CreateSubItem(BaseModel):
    id: int
    name: str


class CreateItem(BaseModel):
    id: int
    name: str
    sub_item_id: int = Field(..., refrences="CreateSubItem.id")


app = FastAPI()

@app.post("/subitem/")
async def create_sub_item(subitem: CreateSubItem):
    ...


@app.post("/item")
async def create_item(item: CreateItem):
    ...

Alternatives

No response

Operating System

Linux

Operating System Details

No response

FastAPI Version

0.78.0

Python Version

3.10.4

Additional Context

No response

[astronuttt]

Well after a little more searching and messing around with this, I managed to implement a link in FastAPI. then found out that this feature is not yet implemented in swagger-UI! swagger-api/swagger-ui#3641

Try-It-Out

...

• Links can't be used to stage another operation

the code i used to create the link:

from fastapi import FastAPI
from pydantic import BaseModel, Field


class CreateSubItem(BaseModel):
    id: int
    name: str


class CreateItem(BaseModel):
    id: int
    name: str
    sub_item_id: int = Field(..., name="sub_item_id")


app = FastAPI()


links = {
    "GetSubItemId": {
        "operationId": "create_item_item_post",
        "parameters": [{"sub_item_id": "$response.body#/id"}],
        "description": "The `id` value returned in the response can be used as the `sub_item_id` value in `POST /item`",
    }
}


@app.post(
    "/subitem/",
    status_code=201,
    responses={201: {"description": "Created", "links": links, "model": CreateSubItem}},
)
async def create_sub_item(subitem: CreateSubItem):
    return {"id": subitem.id, "name": subitem.name}


@app.post("/item")
async def create_item(item: CreateItem):
    return {"id": item.id, "name": item.name, "sub_item_id": item.sub_item_id}

It will be rendered as:

will close the issue for now.

[tiangolo]

Thanks for reporting back and closing the issue 👍

Sorry for the long delay! 🙈 I wanted to personally address each issue/PR and they piled up through time, but now I'm checking each one in order.