Adding examples for Request and Response in openapi.yaml

https://lf-onap.atlassian.net/browse/CPS-774

Issues and Decisions

What Is OpenAPI?

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:

• Available endpoints (/users) and operations on each endpoint (GET /users, POST /users)

• Operation parameters Input and output for each operation

• Authentication methods

• Contact information, license, terms of use and other information.

Adding Examples

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 in a request body:

requestBody:
required: true
content:
application/json:
schema:
type: string
examples:
dataSample:
value:
test:bookstore:
bookstore-name: Chapters
categories:
- code: 01
name: SciFi
- code: 02
name: kids

All request and response body examples in CPS will be added at the object level.

Parameter Examples

Here is an example of a parameter value: 

dataspaceNameInPath:
name: dataspace-name
in: path
description: dataspace-name
required: true
schema:
type: string
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:
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
example:
         $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'

Examples for composite components:

DataAccessRequest:
type: object
properties:
operation:
type: string
enum: [ read, create, update, delete ]
example: create
dataType:
type: string
example: dataTypeValue
data:
type: string
example: data
cmHandleProperties:
$ref: '#/components/schemas/cmHandleProperties'

cmHandleProperties:
type: object
additionalProperties:
type: string
example:
- prop1: value
prop2: value

Schema Type for Request and Response

At present most of the requests are defined as schema type String for Request body json. These could be updated to object type. This will introduce below changes:

Note: These changes will introduce no changes at the client side. All users can continue to use the API as as they are using currently. This could be verified by executing the CSIT test of cps and dmi-plugin.