OpenAPI 3.0 proposal for documented examples

openapi-3.0-documented-examples.yaml

openapi: 3.0.0

paths:
  /money-transfers:
    # Giving information on an example
    get:
      parameters:
        - name: filter
          in: query
          description: A natural language filter
          examples:
            filter-date:
              summary: Filter on time
              description: You can use any sentences containing time data
              value: "before yesterday"
            filter-amount:
              summary: Filter on amount
              description: You can use any sentences containing time data
              value: "more than $100"
            filter-combined:
              summary: Many filters at once
              description: You can combined any parameters
              value: "more than $100 before march 3 2017"
    # Linking request and responses examples by using the key in examples
    post: 
      requestBody:
        content:
          'application/json':
            schema:
              $ref: "#/components/requestBodies/transfer"
            examples:
              # The requestBody is the same for the 2 use cases
              amount-ok:
                $ref: "#/components/examples/simpleTransferRequest"
              amount-ko:
                $ref: "#/components/examples/simpleTransferRequest"
      responses:
        200:
          content:
            'application/json':
              examples:
                # can be linked to the amount-ok requestBody example
                amount-ok:
                  $ref: "#/components/examples/transferResponseOk"
        400:
          content:
            'application/json':
              examples:
                # can be linked to the amount-ko requestBody example
                amount-ko:
                  $ref: "#/components/examples/transferResponseKoBecauseYouDontHaveEnoughMoney"