Page Comparison

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:

...

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. 

...

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:

content:
  application/json:
    schema:
      type: string

content:
  application/json:
    schema:
      type: object

public ResponseEntity<String> createNode
(_, _, final String jsonData, _, _) {

public ResponseEntity<String> createNode
(_, _, final Object jsonData, _, _) {

cpsDataService.saveData(dataspaceName, anchorName, jsonData,
    toOffsetDateTime(observedTimestamp));

cpsDataService.saveData(dataspaceName, anchorName, jsonData.toString(),
    toOffsetDateTime(observedTimestamp));

...