From 996152ac6467946e567ca4e76ce78cc3a3ee0371 Mon Sep 17 00:00:00 2001 From: lukegleeson Date: Tue, 30 Nov 2021 17:06:03 +0000 Subject: Add Examples to DMI-Plugin API Spec Issue-ID: CPS-784 Signed-off-by: lukegleeson Change-Id: I02e450c9c14322fa9c9ac3e14807aeebdb4b9e39 --- openapi/components.yml | 78 +++++++++++++++++++++++++++++--------------------- openapi/openapi.yml | 48 +++++++++++++++++++------------ 2 files changed, 76 insertions(+), 50 deletions(-) (limited to 'openapi') diff --git a/openapi/components.yml b/openapi/components.yml index cdf4c1c0..aa0827a5 100644 --- a/openapi/components.yml +++ b/openapi/components.yml @@ -16,6 +16,7 @@ components: properties: cmHandles: type: array + example: ["cmHandleId1","cmHandleId2","cmHandleId3"] items: type: string @@ -37,9 +38,11 @@ components: type: object properties: name: - $ref: '#/components/schemas/name' + type: string + example: my-name revision: - $ref: '#/components/schemas/revision' + type: string + example: my-revision cmHandleProperties: $ref: '#/components/schemas/cmHandleProperties' @@ -53,10 +56,13 @@ components: properties: moduleName: type: string + example: my-module-name revision: - $ref: '#/components/schemas/revision' + type: string + example: my-revision namespace: type: string + example: my-namespace YangResources: type: array @@ -68,10 +74,13 @@ components: properties: yangSource: type: string + example: my-yang-source moduleName: type: string + example: my-module-name revision: - $ref: '#/components/schemas/revision' + type: string + example: my-revision DataAccessRequest: type: object @@ -79,10 +88,13 @@ components: operation: type: string enum: [ read, create, update, delete ] + example: read dataType: type: string + example: my-data-type data: type: string + example: my-data cmHandleProperties: $ref: '#/components/schemas/cmHandleProperties' @@ -92,60 +104,60 @@ components: type: string example: {"prop1":"value1","prop2":"value2"} - name: - type: string - example: someName - - revision: - type: string - example: someRevision - responses: - NotFound: - description: The specified resource was not found + NoContent: + description: No Content + content: {} + BadRequest: + description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' - BadRequest: - description: Bad Request + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + NotFound: + description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 404 + message: Resource Not Found + details: The requested resource is not found Conflict: description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' - Ok: - description: OK - content: - application/json: - schema: - type: object - Created: - description: Created - content: - text/plain: - schema: - type: string - NoContent: - description: No Content - content: {} + example: + status: 409 + message: Conflicting request + details: The request cannot be processed as the resource is in use. parameters: cmHandleInPath: @@ -155,6 +167,7 @@ components: required: true schema: type: string + example: my-cm-handle resourceIdentifierInQuery: name: resourceIdentifier @@ -164,6 +177,7 @@ components: allowReserved: true schema: type: string + example: my-schema:my-node acceptParamInHeader: name: accept @@ -190,4 +204,4 @@ components: options: (key1=value1,key2=value1/value2) sample3: value: - options: (key1=10,key2=value2,key3=[val31,val32]) \ No newline at end of file + options: (key1=10,key2=value2,key3=val31,val32) \ No newline at end of file diff --git a/openapi/openapi.yml b/openapi/openapi.yml index 5c095a7a..6605a2df 100644 --- a/openapi/openapi.yml +++ b/openapi/openapi.yml @@ -39,12 +39,7 @@ paths: description: Get all modules for given cm handle operationId: getModuleReferences parameters: - - name: cmHandle - in: path - description: The cm handle to fetch all the modules - required: true - schema: - type: string + - $ref: 'components.yml#/components/parameters/cmHandleInPath' requestBody: description: Operational body content: @@ -58,15 +53,6 @@ paths: application/json: schema: $ref: 'components.yml#/components/schemas/ModuleSet' - example: { - "schemas": [ - { - "moduleName": "example-identifier", - "revision": "example-version", - "namespace": "example-namespace" - } - ] - } '400': $ref: 'components.yml#/components/responses/BadRequest' '401': @@ -120,7 +106,12 @@ paths: required: true responses: '201': - $ref: 'components.yml#/components/responses/Created' + description: Created + content: + text/plain: + schema: + type: string + example: cm-handle registered successfully '400': $ref: 'components.yml#/components/responses/BadRequest' '401': @@ -148,7 +139,15 @@ paths: $ref: 'components.yml#/components/schemas/DataAccessRequest' responses: '200': - $ref: 'components.yml#/components/responses/Ok' + description: OK + content: + application/json: + schema: + type: object + example: + - yangSource: my-yang-source + moduleName: my-module-name + revision: my-revision '400': $ref: 'components.yml#/components/responses/BadRequest' '401': @@ -175,7 +174,20 @@ paths: $ref: 'components.yml#/components/schemas/DataAccessRequest' responses: '201': - $ref: 'components.yml#/components/responses/Created' + description: Created + content: + text/plain: + schema: + type: string + examples: + Read: + value: + - yangSource: my-yang-source + moduleName: my-module-name + revision: my-revision + Write: + value: "Created Resource Name" + '400': $ref: 'components.yml#/components/responses/BadRequest' '401': -- cgit 1.2.3-korg