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.