Skip to main content

Support for Multiple Examples Added in API Transformer

· 3 min read

API Transformer now supports multiple examples as an alternative to providing a single example for components. This is a feature available in both OpenAPI v3.0 and RAML v1.0 API description formats and any future transformations between these will see minimized loss of the examples' information.

Details​

OpenAPI v3.0 and RAML v1.0 are two formats that allows its users to specify multiple examples for components where previously only a single example was supported. In APIMatic, only a single example was loaded i.e., if multiple examples were available the first one was loaded by default. Now, with the addition of this feature in API Transformer, we aim to reduce loss of examples information when converting between these two formats. A detailed breakdown of where we support this feature for each format is given below.

Note

Our auto test-case generation feature that generates test cases from examples will remain unaffected and will use the first available example as before.

Support in OpenAPI v3.0​

You can specify multiple examples in OpenAPI v3.0 using the examples map of unique keys and corresponding Example Objects. This property can be specified as a sibling property of wherever the schema property is allowed except for anywhere within the Schema Object. This implies that you cannot specify multiple examples in the Schema Object itself or for its properties.

Note

example and examples are mutually exclusive properties. examples will be given precedence in case both are present.

APIMatic now supports multiple examples for OpenAPI v3.0 at the levels defined below. Globally defined examples under components/examples are also supported.

Parameter Object​

parameters:
  - name: name
    in: query
    schema:
      type: string
    examples:
      example1:
        summary: Example 1
        description: This is the 1st example
        value: dummy name 1
      example2:
        summary: Example 2
        description: This is the 2nd example
        value: dummy name 2
      example3:
        summary: Example 3
        description: This is the 3rd example
        externalValue: >-
          https://example.com#example

Content Media Type Object​

Request Body

requestBody:
  content:
    application/xml:
      schema:
        type: object
        properties:
          id:
            type: string
          name:
            type: string
      examples:
        example1:
          summary: Example 1
          description: This is the 1st example
          value: <root><id>dummy id 1</id><name>dummy name 1<name></root>
        example2:
          summary: Example 2
          description: This is the 2nd example
          value: <root><id>dummy id 2</id><name>dummy name 2<name></root>

Response Body

responses:
  '200':
    content:
      application/json:
        schema:
          properties:
            id:
              type: string
            name:
              type: string
          type: object
        examples:
          example1:
            value:
              id: dummy id 1
              name: dummy name 1
          example2:
            value:
              id: dummy id 2
              name: dummy name 2
          example3:
            externalValue: 'https://example.com#example'

Support in RAML v1.0​

Unlike OpenAPI v3.0, which does not allow multiple examples to be specified in the Schema object, RAML v1.0 allows multiple examples at all places where single examples are supported i.e. wherever a Type Declaration is used (including types, type properties, request parameters and responses). This is now supported by APIMatic as well and an example is shown below:

MyTypeDeclaration:
  examples:
    example1:
      value:
        id: dummy id 1
        name: dummy name 1
    example2:
      displayName: Example2
      description: This is 2nd example
      value:
        id: dummy id 2
        name: dummy name 2
  displayName: MyTypeDeclaration
  type: object
  properties:
    id:
      type: string
    name:
      type: string

Note

example and examples are mutually exclusive properties. examples will be given precedence in case both are present.