From 5d8b24107ad579db89bcdad63476143f4a2db755 Mon Sep 17 00:00:00 2001 From: "puthuparambil.aditya" Date: Wed, 24 Nov 2021 13:35:10 +0000 Subject: Adding examples in openapi for cps-core 1. Added examples for all parameters, request body and response body 2. Changed the response/request type to Object from String for all json objects 3. Passed json format data in all tests 4. PUT and PATCH operations at present return empty response, hence examples are changed to be in sync Issue-ID: CPS-780 Signed-off-by: puthuparambil.aditya Change-Id: If6dd5bb48df4e1bbf1026eaadf315df8f972e282 --- cps-rest/docs/openapi/components.yml | 95 ++++++++++++++++++++++++++++++------ cps-rest/docs/openapi/cpsData.yml | 31 +++++++++--- cps-rest/docs/openapi/cpsQuery.yml | 9 +++- 3 files changed, 111 insertions(+), 24 deletions(-) (limited to 'cps-rest/docs') diff --git a/cps-rest/docs/openapi/components.yml b/cps-rest/docs/openapi/components.yml index 3d2eb57e4d..ff2816af6d 100644 --- a/cps-rest/docs/openapi/components.yml +++ b/cps-rest/docs/openapi/components.yml @@ -25,13 +25,13 @@ components: properties: name: type: string - example: my_anchor + example: my-anchor dataspaceName: type: string - example: my_dataspace + example: my-dataspace schemaSetName: type: string - example: my_schema_set + example: my-schema-set ErrorMessage: type: object @@ -39,13 +39,10 @@ components: properties: status: type: string - example: 400 message: type: string - example: Dataspace not found details: type: string - example: Dataspace with name D1 does not exist. MultipartFile: type: object @@ -56,7 +53,7 @@ components: type: string description: multipartFile format: binary - example: http://example.com/examples/example.yang + example: 'https://github.com/onap/cps/blob/master/cps-service/src/test/resources/bookstore.yang' ModuleReferences: type: object @@ -64,13 +61,13 @@ components: properties: name: type: string - example: module_reference_name + example: my-module-reference-name namespace: type: string - example: module_reference_namespace + example: my-module-reference-namespace revision: type: string - example: module_reference_revision + example: my-module-reference-revision SchemaSetDetails: type: object @@ -78,14 +75,35 @@ components: properties: dataspaceName: type: string - example: my_dataspace + example: my-dataspace moduleReferences: type: array items: $ref: '#/components/schemas/ModuleReferences' name: type: string - example: my_schema_set + example: my-schema-set + + examples: + dataSampleRequest: + value: + test:bookstore: + bookstore-name: Chapters + categories: + - code: 01 + name: SciFi + - code: 02 + name: kids + + dataSampleResponse: + summary: The data node returned does not include the root node. This is being investigated as a part of CPS-461 + value: + bookstore-name: Chapters + categories: + - code: 01 + name: SciFi + - code: 02 + name: kids parameters: dataspaceNameInQuery: @@ -95,6 +113,7 @@ components: required: true schema: type: string + example: my-dataspace dataspaceNameInPath: name: dataspace-name in: path @@ -102,6 +121,7 @@ components: required: true schema: type: string + example: my-dataspace anchorNameInPath: name: anchor-name in: path @@ -109,6 +129,7 @@ components: required: true schema: type: string + example: my-anchor schemaSetNameInQuery: name: schema-set-name in: query @@ -116,6 +137,7 @@ components: required: true schema: type: string + example: my-schema-set schemaSetNameInPath: name: schema-set-name in: path @@ -123,6 +145,7 @@ components: required: true schema: type: string + example: my-schema-set anchorNameInQuery: name: anchor-name in: query @@ -130,29 +153,45 @@ components: required: true schema: type: string + example: my-anchor xpathInQuery: name: xpath in: query - description: xpath + description: For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html required: false schema: type: string default: / + examples: + container xpath: + value: /shops/bookstore + list attributes xpath: + value: /shops/bookstore/categories[@code=1] requiredXpathInQuery: name: xpath in: query - description: xpath + description: For more details on xpath, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html required: true schema: type: string + examples: + container xpath: + value: /shops/bookstore + list attributes xpath: + value: /shops/bookstore/categories[@code=1] cpsPathInQuery: name: cps-path in: query - description: cps-path + description: For more details on cps path, please refer https://docs.onap.org/projects/onap-cps/en/latest/cps-path.html required: false schema: type: string default: / + examples: + container cps path: + value: //bookstore + list attributes cps path: + value: //categories[@code=1] includeDescendantsOptionInQuery: name: include-descendants in: query @@ -161,6 +200,7 @@ components: schema: type: boolean default: false + example: false observedTimestampInQuery: name: observed-timestamp in: query @@ -177,43 +217,66 @@ components: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 404 + message: Resource Not Found + details: The requested resource is not found 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' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden 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 Conflict: description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 409 + message: Conflicting request + details: The request cannot be processed as the resource is in use. Ok: description: OK content: application/json: schema: type: object - example: { "key": "value" } + examples: + dataSampleResponse: + value: "" Created: description: Created content: text/plain: schema: type: string + example: my-resource NoContent: description: No Content content: {} diff --git a/cps-rest/docs/openapi/cpsData.yml b/cps-rest/docs/openapi/cpsData.yml index 2b65ae4400..15f8a1c71b 100644 --- a/cps-rest/docs/openapi/cpsData.yml +++ b/cps-rest/docs/openapi/cpsData.yml @@ -35,7 +35,9 @@ nodeByDataspaceAndAnchor: application/json: schema: type: object - example: { "child": my_child,"leafList": "leafListElement1, leafListElement2", "leaf": my_leaf } + examples: + dataSampleResponse: + $ref: 'components.yml#/components/examples/dataSampleResponse' '400': $ref: 'components.yml#/components/responses/BadRequest' '401': @@ -63,7 +65,10 @@ listElementByDataspaceAndAnchor: content: application/json: schema: - type: string + type: object + examples: + dataSampleRequest: + $ref: 'components.yml#/components/examples/dataSampleRequest' responses: '201': $ref: 'components.yml#/components/responses/Created' @@ -90,10 +95,13 @@ listElementByDataspaceAndAnchor: content: application/json: schema: - type: string + type: object + examples: + dataSampleRequest: + $ref: 'components.yml#/components/examples/dataSampleRequest' responses: '200': - $ref: 'components.yml#/components/responses/Created' + $ref: 'components.yml#/components/responses/Ok' '400': $ref: 'components.yml#/components/responses/BadRequest' '401': @@ -140,7 +148,10 @@ nodesByDataspaceAndAnchor: content: application/json: schema: - type: string + type: object + examples: + dataSampleRequest: + $ref: 'components.yml#/components/examples/dataSampleRequest' responses: '201': $ref: 'components.yml#/components/responses/Created' @@ -167,7 +178,10 @@ nodesByDataspaceAndAnchor: content: application/json: schema: - type: string + type: object + examples: + dataSampleRequest: + $ref: 'components.yml#/components/examples/dataSampleRequest' responses: '200': $ref: 'components.yml#/components/responses/Ok' @@ -216,7 +230,10 @@ nodesByDataspaceAndAnchor: content: application/json: schema: - type: string + type: object + examples: + dataSampleRequest: + $ref: 'components.yml#/components/examples/dataSampleRequest' responses: '200': $ref: 'components.yml#/components/responses/Ok' diff --git a/cps-rest/docs/openapi/cpsQuery.yml b/cps-rest/docs/openapi/cpsQuery.yml index f45f3f41ae..4f938aa891 100644 --- a/cps-rest/docs/openapi/cpsQuery.yml +++ b/cps-rest/docs/openapi/cpsQuery.yml @@ -30,7 +30,14 @@ nodesByDataspaceAndAnchorAndCpsPath: - $ref: 'components.yml#/components/parameters/includeDescendantsOptionInQuery' responses: '200': - $ref: 'components.yml#/components/responses/Ok' + description: OK + content: + application/json: + schema: + type: object + examples: + dataSampleResponse: + $ref: 'components.yml#/components/examples/dataSampleResponse' '400': $ref: 'components.yml#/components/responses/BadRequest' '401': -- cgit 1.2.3-korg