Page History

...

You can add examples to parameters, properties and objects to make OpenAPI specification of your web service clearer. Examples can be read by tools and libraries that process your API in some way. To specify an example, you use the example or examples keys.

...

Request and Response Body Examples

Here is an example of

...

the examples keyword in a request body:

dataspaceNameInPath:
  name: dataspace-name
  in: path
  description: dataspace-name
  required: true
  schema:
    type: string
    example: DataspaceName1
Request Example:
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: string
      examples:
        bookstoreDatadataSample:
          value:
            test:bookstore:
              bookstore-name: Chapters
              categories:
                - code: 01
                  name: SciFi
                - code: 02
                  name: kids
requestBody:

All request required:and true
response body content:
examples in CPS will application/json:
be added at the object level. 

Parameter Examples

Here is an example of a parameter value: 

dataspaceNameInPath schema:
  name: dataspace-name
  in: path
  typedescription: stringdataspace-name
  required: true
   examplesschema:
        objectExample:type: string
          $ref: 'components.yml#/components/examples/testBookStoreData'
example: DataspaceName1

Reusing Examples:

You can define common examples in the components/examples section of your specification and then re-use them in various parameter descriptions, request and response body descriptions, objects and properties:

Sample example defined in components.yaml

components:
  examples:
    dataSample:
  examples:
  testBookStoreData:
    value:
        test:bookstore:
          bookstore-name: Chapters
          categories:
            - code: 01
              name: SciFi
            - code: 02
              name: kids
      summary: A sample data

Sample response using examples defined in components:

responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          type: object
        examples:
          dataSample:
            $ref: 'components.yml#/components/examples/dataSample'

Sample request using examples defined in components:

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: string
      examples:
        dataSample:
          $ref: 'components.yml#/components/examples/dataSample'