How can we reflect the optional/required json items in documentation

[humming-bird-21]

Description

How can I mark the optional/required json elements in the swagger documentation generated using FastAPI?
Currently, for POST verb, it just marked "* required" for the whole body and not individual json elements.

[haizaar]

Are you asking about optional/required fields of the JSON body?

[humming-bird-21]

@haizaar - yes, that's about reflecting the optional/required json elements in the body for swagger documentation

[euri10]

It's working out of the box, if you use pydantic objects the generated schema will "translate" the requirements, for instance this pydantic object from the very beginning of the documentation (https://pydantic-docs.helpmanual.io/):

class UserM(BaseModel):
    id: int
    name = 'John Doe'
    signup_ts: datetime = None
    friends: List[int] = []

used this way:

@app.post("/userm")
async def userm(userm: UserM):
    pass

shows in the documentation as

So quoting pydantic doc, you can check id is required (red star), name has a default so not-required (no red star) etc....

What’s going on here:
id is of type int; the annotation only declaration tells pydantic that this field is required. Strings, bytes or floats will be coerced to ints if possible, otherwise an exception would be raised.
name is inferred as a string from the default, it is not required as it has a default.
signup_ts is a datetime field which is not required (None if it’s not supplied), pydantic will process either a unix timestamp int (e.g. 1496498400) or a string representing the date & time.
friends uses python’s typing system, it is required to be a list of integers, as with id integer-like objects will be converted to integers.

[euri10]

which makes me think reading the spec on
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#requestBodyObject
that the generated schema defaults to True for the request body when the spec defaults to False, I guess a minor thinkg

[humming-bird-21]

thanks, @euri10 and @haizaar

[haizaar]

which makes me think reading the spec on
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#requestBodyObject
that the generated schema defaults to True for the request body when the spec defaults to False, I guess a minor thinkg

@euri10, What if you define the handler as async def userm(userm: UserM = None): (or any other default value)?

[euri10]

if you do that @haizaar the red "required" next to the Request Body disappears

[haizaar]

Which makes sense according to spec I assume, right?

…

On Tue, 16 Jul 2019 at 23:47, euri10 ***@***.***> wrote: if you do that @haizaar <https://github.com/haizaar> the red "required" next to the Request Body disappears — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#388>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAOGWJ3T34J5LV7OVBU5PTP7XGNDANCNFSM4IDVCTHQ> .

-- Zaar

[euri10]

yep indeed, seems like I got things reversed, like right and left, one day it'll be better :)

[tiangolo]

Hehe, thanks for the help @euri10 and @haizaar.

And thanks @sl2016 for reporting back and closing the issue.