openapi: 3.0.0
info:
  title: Providing Examples
  description:  Providing Examples
  version: 1.0.0
paths:
  /multiple-examples-in-request-parameters/{path-param-1}/{path-param-2}:
    get:
      tags:
        - Providing Examples
      parameters:
        - name: 'path-param-1'
          in: 'path'
          schema:
            type: 'string'
            default: "p1-opt-2"  
          examples:
            example1: 
              value: "p1-opt-1"
            example2:
              value: "p1-opt-2"
        - name: 'path-param-2'
          in: 'path'
          schema:
            type: 'string'
          examples:
            example1: 
              value: "p2-opt-1"
            example2:
              value: "p2-opt-2"
        - name: 'age'
          description: Single Example
          in: 'query'
          schema:
            type: 'number'
          example: 24
        - name: 'country-code'
          description: Multiple examples _(Notice `us` do not have a summary)_
          in: 'query'
          schema:
            type: 'string'
            default: " "
          examples:
            example1: 
              value: "uk"
              summary: "United Kingdom"
            example2:
              value: "us"
            example3:
              value: "ch"
              summary: "China"
        - name: 'marital-status'
          in: 'query'
          schema:
            type: 'string'
            default: "unmarried"  
          examples:
            example1: 
              value: "married"
            example2:
              value: "unmarried"
            example3:
              value: "widowed"
        - name: luckyNumbers
          in: query
          schema:
            type: array
            items:
              type: number
            minItems: 4
            maxItems: 4
            examples:
              - ""
              - "   "
              - [10]
              - [10, 20, 30, 40]

  /multiple-examples-by-response-type:
    get:
      description: Multiple Examples provide for each media-type (`application/json` or `application/json`) 
      tags:
        - Providing Examples
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  age:
                    description: Person Age
                    type: integer
                  fullName:
                    description: Person Full name
                    type: object
                    properties:
                      firstName:
                        description: First name
                        type: string
                      lastName:
                        description: Last name
                        type: string
              examples:
                valid-json:
                  summary: Example with Valid JSON String
                  description: If valid JSON is provided in the example, It will be displayed in JSON tree form. Allowing copy/expand/collapse functionality
                  value: |
                    {
                      "person": {
                        "fullName": {
                          "firstName": "Mickey",
                          "lastName": "Mouse"
                        },
                        "age": "9"
                      }
                    }
                invalid-json:
                  summary: Example with Invalid JSON String
                  description: Invalid JSON is displayed in text-area as is
                  value: |
                    {
                      person: {
                        fullName: {
                          firstName: Donald,
                          lastName: Duck
                        },
                        age: 10
                      }
                    }
                as-object:    
                  summary: Example specified as object
                  value:
                    fullName:
                      firstName: Donald
                      lastName: Duck       
                    age: 10
            application/xml:
              schema:
                type: object
                properties:
                  age:
                    description: Person Age
                    type: integer
                  fullName:
                    description: Person Full name
                    type: object
                    properties:
                      firstName:
                        description: First name
                        type: string
                      lastName:
                        description: Last name
                        type: string
              examples:
                example-1:
                  description: Exmple 1 Description
                  value: |
                    <root>
                      <person>
                        <fullName>
                          <firstName> Mickey </firstName>
                          <lastName> Mouse </lastName>
                        </fullName>
                        <age> 9 </age>
                      </person>
                    </root>
  /single-example-by-response-type:
    get:
      summary: Single Example at schema Level
      tags:
        - Providing Examples
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  age:
                    description: Person Age
                    type: integer
                  fullName:
                    description: Person Full name
                    type: object
                    properties:
                      firstName:
                        description: First name
                        type: string
                      lastName:
                        description: Last name
                        type: string
              example: |
                {
                  age: 10,
                  fullName: {
                    firstName: Donald,
                    lastName: Duck
                  }
                }
  /example-with-array-1:
    get:
      summary: Single Example at schema Level
      tags:
        - Providing Examples
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArrayOfInt-1"
  /example-with-array-2:
    get:
      summary: Single Example at schema Level
      tags:
        - Providing Examples
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArrayOfInt-2"

  /object-example-for-a-schema:
    get:
      summary: Single example having invalid JSON, under a Schema
      tags:
        - Providing Examples
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  age:
                    description: Person Age
                    type: integer
                  fullName:
                    description: Person Full name
                    type: object
                    properties:
                      firstName:
                        description: First name
                        type: string
                      lastName:
                        description: Last name
                        type: string
                example: |
                  {
                    person: {
                      fullName: {
                        firstName: Donald,
                        lastName: Duck
                      },
                      age: 10
                    }
                  }
  /array-example-for-a-schema:
    get:
      summary: Single Example of Type Array Under a Schema
      tags:
        - Providing Examples
      responses:
        '200':
          description: An array of currency codes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/currencies"
  /example-with-simple-object:
    get:
      summary: Single Example of Type Array Under a Schema
      tags:
        - Providing Examples
      responses:
        '200':
          description: An array of currency codes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonObject"
  /per-field-example-with-root-as-object:
    get:
      summary: Root node of the example is an object. and the object is constituted using field level example
      tags:
        - Providing Examples
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  age:
                    description: Person Age
                    type: integer
                    example: 8
                  fullName:
                    description: Person Full name
                    type: object
                    properties:
                      firstName:
                        description: First name
                        type: string
                        example: 'Daisy'
                      lastName:
                        description: Last name
                        type: string
                        example: 'Duck'
                  dependents:
                    type: array
                    items:
                      type: object
                      properties:
                        dependentName:
                          type: string
                        relation:
                          type: string
                        age:
                          type: number
  /per-field-example-with-root-as-array:
    get:
      summary: Root node of the example is an array. and the object is constituted using field level example
      tags:
        - Providing Examples
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    dependentName:
                      type: string
                    relation:
                      type: string
                    age:
                      type: number
                  example:
                    dependentName: Natasha
                    relation: wife
                    age: 28    
  /example-with-refs:
    get:
      description: |
        When a Schema definition is `provided` as a ref  
        (provide the example at schema-level)
      tags:
        - Providing Examples
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/cost'
              examples:
                USD:
                  description: Cost in `US Dollars`
                  value: |
                    {
                      amount: 10,
                      currency: USD
                    }
                INR:
                  description: Cost in `Indian Rupees`
                  value: |
                    {
                      amount: 700,
                      currency: INR
                    }
  /multiple-example-in-request-body:
    post:
      summary: Request body with multiple examples
      tags:
        - Providing Examples
      requestBody:
        description: Request body containing **multiple** examples
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/cost'
            examples:
              USD:
                description: Cost in `US Dollars`
                value: |
                  {
                    amount: 10,
                    currency: USD
                  }
              INR:
                description: Cost in `Indian Rupees`
                value: |
                  {
                    amount: 700,
                    currency: INR
                  }
  /object-containg-array-property-with-example:
    get:
      summary: Object schema with array type property containing example
      tags:
        - Providing Examples
      responses:
        200:
          description: Object with array type property containing example
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectWithArrayPropExample"
  /examples-anyOf:
    get:
      tags:
        - Providing Examples
      summary: AnyOf schemas with examples as part of the subschema
      responses:
        '200':
          description: AnyOf schemas with examples as part of the subschema
          content:
            application/problem+json:
              schema:
                anyOf:
                  - title: AnyOf example 1
                    description: First example
                    type: object
                    properties:
                      foo:
                        type: string
                      bar:
                        type: integer
                    example:
                      foo: foo
                      bar: 42
                  - title: Second anyOf
                    description: Another example
                    type: array
                    items:
                      type: object
                      properties:
                        foo:
                          type: string
                        quux:
                          type: array
                          items:
                            type: number
                    example:
                      foo: foo
                      quux: [ 42, 24 ]
                  - title: No example defined
                    type: array
                    items:
                      type: object
                      properties:
                        foo:
                          type: string
                        quux:
                          type: array
                          items:
                            type: number
  /examples-anyOf-with-general-properties:
    get:
      tags:
        - Providing Examples
      summary: AnyOf schemas with general properties 
      responses:
        '200':
          description: AnyOf schemas with general properties
          content:
            application/problem+json:
              schema:
                title: A composed object
                type: object
                properties:
                  common:
                    type: string
                  other:
                    type: number
                anyOf:
                  - title: Schema 1
                    type: object
                    properties:
                      foo:
                        type: string
                      bar:
                        type: integer
                    example:
                      foo: foo
                      bar: 42
                  - title: Second schema
                    type: object
                    properties:
                      baz:
                        type: string
                        format: url
  /examples-oneOf:
    get:
      tags:
        - Providing Examples
      summary: OneOf schema with examples as part of the subschema
      responses:
        '200':
          description: OneOf schema with examples as part of the subschema
          content:
            application/problem+json:
              schema:
                oneOf:
                  - title: Schema 1
                    type: object
                    properties:
                      foo:
                        type: string
                      bar:
                        type: integer
                    example:
                      foo: foo
                      bar: 42
                  - title: Second schema
                    type: object
                    properties:
                      baz:
                        type: string
                        format: url
  /examples-allOf:
    get:
      tags:
        - Providing Examples
      summary: AllOf schemas with examples as part of the subschema
      responses:
        '200':
          description: AllOf schemas with examples as part of the subschema
          content:
            application/problem+json:
              schema:
                allOf:
                  - title: Schema 1
                    type: object
                    properties:
                      foo:
                        type: string
                      bar:
                        type: integer
                  - title: Second schema
                    type: object
                    properties:
                      baz:
                        type: string
                        format: url
  /examples-allOf-anyOf:
    get:
      tags:
        - Providing Examples
      summary: Combination of allOf & nested anyOf schemas
      responses:
        '200':
          description: Combination of allOf & nested anyOf schemas
          content:
            application/problem+json:
              schema:
                allOf:
                  - title: Schema 1
                    type: object
                    properties:
                      foo:
                        type: string
                      bar:
                        type: integer
                  - title: Second schema
                    anyOf:
                      - type: object
                        properties:
                          baz:
                            type: string
                            format: url
                      - type: object
                        properties:
                          foobar:
                            type: string
components:
  schemas:
    cost:
      type: object
      properties:
        amount:
          type: integer
          description: Amount
        currency:
          description: Currency Code
          type: string
    currencies:
      type: array
      items:
        type: object
        properties:
          currencyCode:
            type: string
          evaluationDate:
            type: string
            format: date-time
      example:
        - currencyCode: USD
          evaluationDate: '2017-07-21T17:32:28Z'
        - currencyCode: INR
          evaluationDate: '2017-07-21T17:32:28Z'
    ArrayOfInt-1:
      type: array
      items:
        type: integer
        format: int64
      example: [1, 2, 3, 4]
    ArrayOfInt-2:
      type: array
      items:
        type: integer
        format: int64
        example: 1
    PersonObject:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
      example:
        name: name-1
        age: 1
    ObjectWithArrayPropExample:
      type: object
      properties:
        numberProp:
          type: number
          example: 1000
        stringProp:
          type: string
          enum: [value0, value1]
        arrayProp:
          type: array
          items:
            type: number
          example: [0, 1, 2]