[FEATURE] Enable support for multiple request body "examples" in openapi / swagger ui docs

This feature is related to issue #372

It appears to me in the Swagger UI documentation on adding examples that the ‘examples’ key belongs to ‘application/json’. It also appears to me that the key already exists in the MediaType model within fastapi.openapi.models but that only the ‘schema’ key is modified when writing the openapi spec through fastapi.openapi.utils.get_openapi_operation_request_body and then fastapi.openapi.utils.get_open_api_path and that the media type is nearly always passed around as a string rather than a dict or model object (please correct me if I’m wrong, I’ve only been using these particular tools for a few months.)

pydantic recently enabled schema_extra in samuelcolvin/pydantic#663 but I can’t seem to get it to work with the swagger docs. At this time it’s unclear to me if this is simply a part of the json schema spec that the swagger ui doesn’t recognize yet, or if it’s actually a deliberate deviation from the spec, or if I just can’t figure it out. From the JSON Schema documentation on “examples” it states that this field “MUST” be an array. The aforementioned pydantic PR#663 and the associated example adhere to the spec well, but I cannot seem to build a request model using this newly minted ability that is supported by the swagger docs.

Here’s a working reference swagger ui yaml file that builds the dropdown examples pick list in the swagger editor. I started with the fastapi.docs.body_fields.tutorial_002.py example and hand edited the swagger ui yaml to match the swagger examples docs for multiple examples:

openapi: 3.0.2
info:
  title: Fast API
  version: 0.1.0
paths:
  '/items/{item_id}':
    put:
      summary: Update Item
      operationId: update_item_items__item_id__put
      parameters:
        - required: true
          schema:
            title: Item Id
            type: integer
          name: item_id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              title: Item
              allOf:
                - $ref: '#/components/schemas/Item'
            examples:
              test1:
                  summary: first test
                  value:
                    name: Foo
                    description: A very nice Item
                    price: 35.4
                    tax: 3.2
              test2:
                  summary: second test
                  value:
                    name: Bar
                    description: Another very nice Item
                    price: 30
                    tax: 1.1
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      title: HTTPValidationError
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    Item:
      title: Item
      required:
        - name
        - price
      type: object
      properties:
        name:
          title: Name
          type: string
        description:
          title: Description
          type: string
        price:
          title: Price
          type: number
        tax:
          title: Tax
          type: number
    ValidationError:
      title: ValidationError
      required:
        - loc
        - msg
        - type
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            type: string
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string

My hope is that either 1) There is another way to add multiple examples for a request body that I am missing or that 2) we can build a means for adding the “examples” dictionary to the media type so it appears in the swagger ui per their documented format, preferably building from the recent pydantic PR referenced above.

I recognize that a few things complicate this effort, including the fact that a fastapi Route can include multiple Body objects. This might mean that if we support the documented swagger format linked above for multiple examples, the attribute might have to be moved out of the Body function/class so that only one “examples” dict can be specified per route, or better yet, per content media type somehow.

With some direction I think I would be able to help implement this, since it’s not a mission critical feature for the lead developers.

[austinorr]

went ahead and opened a PR so the diff and example/tutorial is easier to review.

[tiangolo]

Thanks for all the discussion and arguments here everyone! 🤓 ☕

It helped me to clarify and understand better all the context and everything.

And thanks @austinorr for the work on the PR! 🚀

I updated it a bit and added support for example and examples also in parameters like Path(), Query(), etc. A lot more of the technical details are in the comment: https://github.com/tiangolo/fastapi/pull/1267#issuecomment-832911064

This will be available in the next release of FastAPI, 0.64.0, in the next couple of days. 🎉