fastapi/fastapiPublic

NotificationsYou must be signed in to change notification settings
Fork8.7k
Star95.4k

✨ Support Python internal description on Pydantic model's docstring#3032

Merged

tiangolo merged 3 commits intofastapi:masterfrom

Kludex:feat/comment-on-pydantic-models

Sep 2, 2022

Merged

✨ Support Python internal description on Pydantic model's docstring#3032
tiangolo merged 3 commits intofastapi:masterfrom
Kludex:feat/comment-on-pydantic-models

Conversation

Copy link

Member

Kludex commentedApr 1, 2021•
edited
Loading

Problem

Currently, on FastAPI endpoint functions we can document for OpenAPI description/Swagger and for internal Python purposes:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()@app.get("/")defuseful():"""My description.\f    Internal documentation.    """    ...

On Swagger we'll have:

When documenting models, it doesn't have the same behavior:

fromenumimportEnumfromfastapiimportFastAPIclassBanana(str,Enum):"""My description.\f    Internal documentation.    """HAHA="haha"HOHO="hoho"app=FastAPI()@app.get("/")defuseful(banana:Banana):    ...

On Swagger, we'll have:

Solution

The proposedtwo lines of code on this PR, makes it possible to have the same behavior as the endpoint description:

It follows the same idea as:https://github.com/tiangolo/fastapi/blob/10397ddc30ef9bb26e9247f04fe20ce3045081c4/fastapi/routing.py#L350

Related issues

Should Feed Escape work in Pydantic Models #3024

Questions & Alternatives

Should Pydantic handle this on themodel_process_schema() function instead?

✨ Support Python internal description on Pydantic model's docstrings

00da79c

Copy link

MemberAuthor

Kludex commentedApr 1, 2021•
edited
Loading

Do you guys have an opinion on this?@PrettyWood @samuelcolvin

Copy link

Contributor

github-actionsbot commentedApr 1, 2021

📝 Docs preview for commit00da79c at:https://606608e5d9c9b620c64fe21f--fastapi.netlify.app

🐛 Only add description if already exists

1c93179

Copy link

codecovbot commentedApr 1, 2021•
edited
Loading

Codecov Report

Merging#3032 (00becde) intomaster (b1d0f1e) willnot change coverage.
The diff coverage is100.00%.

@@            Coverage Diff            @@##            master     #3032   +/-   ##=========================================  Coverage   100.00%   100.00%           =========================================  Files          538       538             Lines        13870     13872    +2     =========================================+ Hits         13870     13872    +2

Impacted Files	Coverage Δ
fastapi/utils.py	`100.00% <100.00%> (ø)`

Help us with your feedback. Take ten seconds to tell ushow you rate us. Have a feature suggestion?Share it here.

Copy link

Contributor

github-actionsbot commentedApr 1, 2021

📝 Docs preview for commit1c93179 at:https://60660aa9f6c5301f7f6c8b97--fastapi.netlify.app

Kludex changed the title~~✨ Support Python internal description on Pydantic model's docstrings~~✨ Support Python internal description on Pydantic model's docstring

Apr 1, 2021

Copy link

killswitch-GUI commentedJul 14, 2021

Just bumping.

Copy link

killswitch-GUI commentedOct 14, 2021

@Kludex Think this one will make it in?

Copy link

MemberAuthor

Kludex commentedOct 14, 2021

I don't know. 😗

Merge branch 'master' into feat/comment-on-pydantic-models

00becde

Copy link

Contributor

github-actionsbot commentedSep 2, 2022

📝 Docs preview for commit00becde at:https://6311f9a78e0d811162b5915a--fastapi.netlify.app

tiangolo changed the title~~✨ Support Python internal description on Pydantic model's docstring~~✨ Support Python internal description on Pydantic model's docstring

Sep 2, 2022