Jira | ||||||
---|---|---|---|---|---|---|
|
Adding Responses for API operations
An API specification needs to specify the responses
for all API operations. Each operation must have at least one response defined, usually a successful response. A response is defined by its HTTP status code and the data returned in the response body and/or headers.
Reusing
...
Response
As multiple operations return the same response (status code and data), the responses
section is defined as a global components
object and then reference via $ref
at the operation level. This is useful for error responses with the same status codes and response body. In CPS, even the success scenarios are included in the responses section as shown below.
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
schemas: AnchorDetails: type: object title: Anchor details by anchor Name properties: name: type: string example: Anchormy_1anchor dataspaceName: type: string example: Dataspacemy_1dataspace schemaSetName: type: string example: Schemamy_schema_set_1 |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
ArrayOfAnchors: type: array items: type: object properties: name: type: string example: my_anchor dataspace: type: string example: my_dataspace schemaSet: type: string example: my-schema-set $ref: 'components.yml#/components/schemas/AnchorDetails' |
These schemas could be used in the API specification as below:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
'/v1/dataspaces/{dataspace-name}/anchors':
get:
description: 'Read all anchors, given a dataspace'
tags:
- cps-admin
summary: Get anchors
operationId: getAnchors
parameters:
- name: dataspace-name
in: path
description: dataspace-name
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ArrayOfAnchors'
'400':
$ref: 'components.yml#/components/responses/BadRequest'
'401':
$ref: 'components.yml#/components/responses/Unauthorized'
'403':
$ref: 'components.yml#/components/responses/Forbidden'
'404':
$ref: 'components.yml#/components/responses/NotFound' |
This change would also introduce change changes in the object returned for these API implementation methods in the Controller class.
...
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. For example, an API mocking tool can use sample values to generate mock requests. In CPS, the examples are added at object and property level.
For schema set and data node, the bookstore model and data should be used as example.
- Schema Set : https://github.com/onap/cps/blob/master/cps-service/src/test/resources/bookstore.yang
- Data : https://github.com/onap/cps/blob/master/cps-service/src/test/resources/bookstore.json
Note: ErrorMessage is a common schema used for all error scenarios. And as the examples as defined at property level, different errors correspond to the same example.
...