Fastapi: [QUESTION] "Examples" empty select box in Swagger UI doc

[otsuka]

I run the sample notes app of the tutorial.

Opening the API documentation with Swagger UI, I found an empty select box labeled "Examples" in Request body block as images below.

What is this select box? What is this use?
How can I set a value in the select box?

Try it out button Clicked

[dmontagu]

Oh man, this looks like it could be really useful as a way to quickly convey/grasp how a given endpoint should be used (especially if the endpoint has a complex or deeply/variably-nested input model).

@tiangolo if https://github.com/samuelcolvin/pydantic/pull/663 makes it possible to easily add examples that can be selected in this drop down, I think that will be worth a specific call-out in the fastapi docs!

[eabrouwer3]

This should work in your case. I'm wondering. Should we add it to the fastapi docs where the previously mentioned example property could be set for a specific response ("Additional Responses in OpenAPI")? Or should we add it maybe to the "Extending OpenAPI" section? Or somewhere else entirely, like here where it talks about Pydantic models for the first time? Thoughts?

[fgimian]

It seems this has been merged in Pydantic. I'm hoping it'll allow us to specify examples in the OpenAPI JSON with FastAPI as per the following snippet from the petstore example:

        username:
          description: User supplied username
          type: string
          minLength: 4
          example: John78
        firstName:
          description: User first name
          type: string
          minLength: 1
          example: John
        lastName:
          description: User last name
          type: string
          minLength: 1
          example: Smith
        email:
          description: User email address
          type: string
          format: email
          example: [email protected]

In our case, we have rather complex data inputs and many many parameters for various API endpoints. Having real examples of what the expected input data looks like would be greatly beneficial to consumers of our API.

Thanks heaps guys
Fotis

[tiangolo]

Indeed, this would be a great addition to the docs, probably in the Advanced User Guide.

[tiangolo]

There's a new section in the docs with this: https://fastapi.tiangolo.com/tutorial/schema-extra-example/ :tada:

[github-actions[bot]]

Assuming the original issue was solved, it will be automatically closed now. But feel free to add more comments or create new issues.