From a1129b696f3197fc7d8a3b63bcd84b5b2dd8874e Mon Sep 17 00:00:00 2001 From: Bruno Sakoto Date: Tue, 15 Mar 2022 08:09:07 -0400 Subject: Create primary documentation for Jakarta release * Update release notes * Update openapi documentation * Fix section title hierarchy * Fix admin container directive not found Issue-ID: CPS-935 Signed-off-by: Bruno Sakoto Change-Id: Iabdc357aa0168c1becafd6de1ac7703ec3bd1afa --- docs/admin-guide.rst | 2 - docs/api/swagger/cps/openapi.yaml | 1350 +++++++++++++++++++------- docs/api/swagger/ncmp/openapi-inventory.yaml | 15 +- docs/api/swagger/ncmp/openapi.yaml | 26 +- docs/deployment.rst | 11 +- docs/index.rst | 13 +- docs/overview.rst | 24 +- docs/release-notes.rst | 28 +- 8 files changed, 1054 insertions(+), 415 deletions(-) diff --git a/docs/admin-guide.rst b/docs/admin-guide.rst index 203151bf8f..135040faaf 100644 --- a/docs/admin-guide.rst +++ b/docs/admin-guide.rst @@ -49,8 +49,6 @@ CPS Log pattern Change logging level -------------------- -.. container:: ulist - - Curl command 1. Check current log level of "logging.level.org.onap.cps" if it is set to it's default value (INFO) .. code-block:: java diff --git a/docs/api/swagger/cps/openapi.yaml b/docs/api/swagger/cps/openapi.yaml index 2fc8d7f338..983252f5af 100644 --- a/docs/api/swagger/cps/openapi.yaml +++ b/docs/api/swagger/cps/openapi.yaml @@ -15,27 +15,28 @@ info: x-logo: url: cps_logo.png servers: - - url: /cps/api +- url: /cps/api tags: - - name: cps-admin - description: cps Admin - - name: cps-data - description: cps Data +- name: cps-admin + description: cps Admin +- name: cps-data + description: cps Data paths: /v1/dataspaces: post: tags: - - cps-admin + - cps-admin summary: Create a dataspace description: Create a new dataspace operationId: createDataspace parameters: - - name: dataspace-name - in: query - description: dataspace-name - required: true - schema: - type: string + - name: dataspace-name + in: query + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace responses: "201": description: Created @@ -43,38 +44,130 @@ paths: text/plain: schema: type: string + example: my-resource + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized + "403": + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "409": + 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. + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred + delete: + tags: + - cps-admin + summary: Delete a dataspace + description: Delete a dataspace + operationId: deleteDataspace + parameters: + - name: dataspace-name + in: query + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + responses: + "204": + description: No Content + content: {} "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "409": + 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. + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred /v1/dataspaces/{dataspace-name}/anchors: get: tags: - - cps-admin + - cps-admin summary: Get anchors description: "Read all anchors, given a dataspace" operationId: getAnchors parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace responses: "200": description: OK @@ -90,49 +183,68 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' - "404": - description: The specified resource was not found + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred post: tags: - - cps-admin + - cps-admin summary: Create an anchor description: Create a new anchor in the given dataspace operationId: createAnchor parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: schema-set-name - in: query - description: schema-set-name - required: true - schema: - type: string - - name: anchor-name - in: query - description: anchor-name - required: true - schema: - type: string + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: schema-set-name + in: query + description: schema-set-name + required: true + schema: + type: string + example: my-schema-set + - name: anchor-name + in: query + description: anchor-name + required: true + schema: + type: string + example: my-anchor responses: "201": description: Created @@ -140,44 +252,79 @@ paths: text/plain: schema: type: string + example: my-resource "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "409": + 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. + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}: get: tags: - - cps-admin + - cps-admin summary: Get an anchor description: Read an anchor given an anchor name and a dataspace operationId: getAnchor parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: anchor-name - in: path - description: anchor-name - required: true - schema: - type: string + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor responses: "200": description: OK @@ -191,43 +338,61 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' - "404": - description: The specified resource was not found + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred delete: tags: - - cps-admin + - cps-admin summary: Delete an anchor description: Delete an anchor given an anchor name and a dataspace operationId: deleteAnchor parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: anchor-name - in: path - description: anchor-name - required: true - schema: - type: string + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor responses: "204": description: No Content @@ -238,38 +403,62 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred /v1/dataspaces/{dataspace-name}/schema-sets: post: tags: - - cps-admin + - cps-admin summary: Create a schema set description: Create a new schema set in the given dataspace operationId: createSchemaSet parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: schema-set-name - in: query - description: schema-set-name - required: true - schema: - type: string + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: schema-set-name + in: query + description: schema-set-name + required: true + schema: + type: string + example: my-schema-set requestBody: content: multipart/form-data: @@ -283,44 +472,79 @@ paths: text/plain: schema: type: string + example: my-resource "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "409": + 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. + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred /v1/dataspaces/{dataspace-name}/schema-sets/{schema-set-name}: get: tags: - - cps-admin + - cps-admin summary: Get a schema set description: Read a schema set given a schema set name and a dataspace operationId: getSchemaSet parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: schema-set-name - in: path - description: schema-set-name - required: true - schema: - type: string + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: schema-set-name + in: path + description: schema-set-name + required: true + schema: + type: string + example: my-schema-set responses: "200": description: OK @@ -334,43 +558,61 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' - "404": - description: The specified resource was not found + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred delete: tags: - - cps-admin + - cps-admin summary: Delete a schema set description: Delete a schema set given a schema set name and a dataspace operationId: deleteSchemaSet parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: schema-set-name - in: path - description: schema-set-name - required: true - schema: - type: string + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: schema-set-name + in: path + description: schema-set-name + required: true + schema: + type: string + example: my-schema-set responses: "204": description: No Content @@ -381,59 +623,93 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden "409": 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. + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/node: get: tags: - - cps-data + - cps-data summary: Get a node description: Get a node with an option to retrieve all the children for a given anchor and dataspace operationId: getNodeByDataspaceAndAnchor parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: anchor-name - in: path - description: anchor-name - required: true - schema: - type: string - - name: xpath - in: query - description: xpath - required: false - schema: - type: string - default: / - - name: include-descendants - in: query - description: include-descendants - required: false - schema: - type: boolean - default: false + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor + - name: xpath + in: query + 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]" + - name: include-descendants + in: query + description: include-descendants + required: false + schema: + type: boolean + example: false + default: false responses: "200": description: OK @@ -441,75 +717,100 @@ paths: application/json: schema: type: object - example: - child: my_child - leafList: "leafListElement1, leafListElement2" - leaf: my_leaf + examples: + dataSample: + $ref: '#/components/examples/dataSample' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' - "404": - description: The specified resource was not found + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred x-codegen-request-body-name: xpath /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes: put: tags: - - cps-data + - cps-data summary: Replace a node with descendants description: "Replace a node with descendants for a given dataspace, anchor\ \ and a parent node xpath" operationId: replaceNode parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: anchor-name - in: path - description: anchor-name - required: true - schema: - type: string - - name: xpath - in: query - description: xpath - required: false - schema: - type: string - default: / - - name: observed-timestamp - in: query - description: observed-timestamp - required: false - schema: - type: string - example: 2021-03-21T00:10:34.030-0100 + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor + - name: xpath + in: query + 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]" + - name: observed-timestamp + in: query + description: observed-timestamp + required: false + schema: + type: string + example: 2021-03-21T00:10:34.030-0100 requestBody: content: application/json: schema: - type: string + type: object + examples: + dataSample: + $ref: '#/components/examples/dataSample' required: true responses: "200": @@ -518,64 +819,97 @@ paths: application/json: schema: type: object - example: - key: value + examples: + dataSample: + value: "" "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred post: tags: - - cps-data + - cps-data summary: Create a node description: Create a node for a given anchor and dataspace operationId: createNode parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: anchor-name - in: path - description: anchor-name - required: true - schema: - type: string - - name: xpath - in: query - description: xpath - required: false - schema: - type: string - default: / - - name: observed-timestamp - in: query - description: observed-timestamp - required: false - schema: - type: string - example: 2021-03-21T00:10:34.030-0100 + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor + - name: xpath + in: query + 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]" + - name: observed-timestamp + in: query + description: observed-timestamp + required: false + schema: + type: string + example: 2021-03-21T00:10:34.030-0100 requestBody: content: application/json: schema: - type: string + type: object + examples: + dataSample: + $ref: '#/components/examples/dataSample' required: true responses: "201": @@ -584,63 +918,191 @@ paths: text/plain: schema: type: string + example: my-resource + "400": + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized + "403": + description: Forbidden + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "409": + 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. + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred + delete: + tags: + - cps-data + summary: Delete a data node + description: Delete a datanode for a given dataspace and anchor given a node + xpath. + operationId: deleteDataNode + parameters: + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor + - name: xpath + in: query + 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]" + - name: observed-timestamp + in: query + description: observed-timestamp + required: false + schema: + type: string + example: 2021-03-21T00:10:34.030-0100 + responses: + "204": + description: No Content + content: {} "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred patch: tags: - - cps-data + - cps-data summary: Update node leaves description: Update a data node leaves for a given dataspace and anchor and a parent node xpath operationId: updateNodeLeaves parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: anchor-name - in: path - description: anchor-name - required: true - schema: - type: string - - name: xpath - in: query - description: xpath - required: false - schema: - type: string - default: / - - name: observed-timestamp - in: query - description: observed-timestamp - required: false - schema: - type: string - example: 2021-03-21T00:10:34.030-0100 + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor + - name: xpath + in: query + 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]" + - name: observed-timestamp + in: query + description: observed-timestamp + required: false + schema: + type: string + example: 2021-03-21T00:10:34.030-0100 requestBody: content: application/json: schema: - type: string + type: object + examples: + dataSample: + $ref: '#/components/examples/dataSample' required: true responses: "200": @@ -649,129 +1111,195 @@ paths: application/json: schema: type: object - example: - key: value + examples: + dataSample: + value: "" "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/list-nodes: put: tags: - - cps-data - summary: Replace list-node child element(s) under existing parent node - description: Replace list-node child elements under existing node for a given - anchor and dataspace - operationId: replaceListNodeElements + - cps-data + summary: Replace list content + description: "Replace list content under a given parent, anchor and dataspace" + operationId: replaceListContent parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: anchor-name - in: path - description: anchor-name - required: true - schema: - type: string - - name: xpath - in: query - description: xpath - required: true - schema: - type: string - - name: observed-timestamp - in: query - description: observed-timestamp - required: false - schema: - type: string - example: 2021-03-21T00:10:34.030-0100 + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor + - name: xpath + in: query + 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]" + - name: observed-timestamp + in: query + description: observed-timestamp + required: false + schema: + type: string + example: 2021-03-21T00:10:34.030-0100 requestBody: content: application/json: schema: - type: string + type: object + examples: + dataSample: + $ref: '#/components/examples/dataSample' required: true responses: "200": - description: Created + description: OK content: - text/plain: + application/json: schema: - type: string + type: object + examples: + dataSample: + value: "" "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred post: tags: - - cps-data - summary: Add list-node child element(s) under existing parent node - description: Add list-node child elements to existing node for a given anchor - and dataspace - operationId: addListNodeElements + - cps-data + summary: Add list element(s) + description: Add list element(s) to a list for a given anchor and dataspace + operationId: addListElements parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: anchor-name - in: path - description: anchor-name - required: true - schema: - type: string - - name: xpath - in: query - description: xpath - required: true - schema: - type: string - - name: observed-timestamp - in: query - description: observed-timestamp - required: false - schema: - type: string - example: 2021-03-21T00:10:34.030-0100 + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor + - name: xpath + in: query + 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]" + - name: observed-timestamp + in: query + description: observed-timestamp + required: false + schema: + type: string + example: 2021-03-21T00:10:34.030-0100 requestBody: content: application/json: schema: - type: string + type: object + examples: + dataSample: + $ref: '#/components/examples/dataSample' required: true responses: "201": @@ -780,57 +1308,86 @@ paths: text/plain: schema: type: string + example: my-resource "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred delete: tags: - - cps-data - summary: Delete list-node child element(s) under existing parent node - description: Delete list-node child elements under existing node for a given - anchor and dataspace - operationId: deleteListNodeElements + - cps-data + summary: Delete one or all list element(s) + description: Delete one or all list element(s) for a given anchor and dataspace + operationId: deleteListOrListElement parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: anchor-name - in: path - description: anchor-name - required: true - schema: - type: string - - name: xpath - in: query - description: xpath - required: true - schema: - type: string - - name: observed-timestamp - in: query - description: observed-timestamp - required: false - schema: - type: string - example: 2021-03-21T00:10:34.030-0100 + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor + - name: xpath + in: query + 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]" + - name: observed-timestamp + in: query + description: observed-timestamp + required: false + schema: + type: string + example: 2021-03-21T00:10:34.030-0100 responses: "204": description: No Content @@ -841,52 +1398,83 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred + deprecated: true /v1/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes/query: get: tags: - - cps-query + - cps-query summary: Query data nodes description: Query data nodes for the given dataspace and anchor using CPS path operationId: getNodesByDataspaceAndAnchorAndCpsPath parameters: - - name: dataspace-name - in: path - description: dataspace-name - required: true - schema: - type: string - - name: anchor-name - in: path - description: anchor-name - required: true - schema: - type: string - - name: cps-path - in: query - description: cps-path - required: false - schema: - type: string - default: / - - name: include-descendants - in: query - description: include-descendants - required: false - schema: - type: boolean - default: false + - name: dataspace-name + in: path + description: dataspace-name + required: true + schema: + type: string + example: my-dataspace + - name: anchor-name + in: path + description: anchor-name + required: true + schema: + type: string + example: my-anchor + - name: cps-path + in: query + 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]" + - name: include-descendants + in: query + description: include-descendants + required: false + schema: + type: boolean + example: false + default: false responses: "200": description: OK @@ -894,32 +1482,49 @@ paths: application/json: schema: type: object - example: - key: value + examples: + dataSample: + $ref: '#/components/examples/dataSample' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 400 + message: Bad Request + details: The provided request is not valid "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 401 + message: Unauthorized request + details: This request is unauthorized "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' - "404": - description: The specified resource was not found + example: + status: 403 + message: Request Forbidden + details: This request is forbidden + "500": + description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' + example: + status: 500 + message: Internal Server Error + details: Internal Server Error occurred x-codegen-request-body-name: xpath components: schemas: @@ -929,29 +1534,26 @@ 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. AnchorDetails: title: Anchor details by anchor Name type: object 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 MultipartFile: required: - - file + - file type: object properties: file: @@ -960,28 +1562,40 @@ components: format: binary SchemaSetDetails: title: Schema set details by dataspace and schemasetName + required: + - moduleReferences type: object 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 ModuleReferences: title: Module reference object type: object 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 + examples: + dataSample: + value: + test:bookstore: + bookstore-name: Chapters + categories: + - code: 1 + name: SciFi + - code: 2 + name: kids diff --git a/docs/api/swagger/ncmp/openapi-inventory.yaml b/docs/api/swagger/ncmp/openapi-inventory.yaml index 154a4411da..30896f6068 100644 --- a/docs/api/swagger/ncmp/openapi-inventory.yaml +++ b/docs/api/swagger/ncmp/openapi-inventory.yaml @@ -86,23 +86,16 @@ components: $ref: '#/components/schemas/RestInputCmHandle' updatedCmHandles: type: array - example: - cmHandle: my-cm-handle - cmHandleProperties: - add-my-property: add-property - update-my-property: updated-property - delete-my-property: ~ - publicCmHandleProperties: - add-my-property: add-property - update-my-property: updated-property - delete-my-property: ~ items: $ref: '#/components/schemas/RestInputCmHandle' removedCmHandles: type: array + example: + - my-cm-handle1 + - my-cm-handle2 + - my-cm-handle3 items: type: string - example: "[\"my-cm-handle1\",\"my-cm-handle2\",\"my-cm-handle3\"]" RestInputCmHandle: required: - cmHandle diff --git a/docs/api/swagger/ncmp/openapi.yaml b/docs/api/swagger/ncmp/openapi.yaml index b7a65632e7..5a6a600a36 100644 --- a/docs/api/swagger/ncmp/openapi.yaml +++ b/docs/api/swagger/ncmp/openapi.yaml @@ -70,6 +70,17 @@ paths: sample 3: value: options: "(depth=2,fields=book/authors)" + - name: topic + in: query + description: topic parameter in query. + required: false + allowReserved: true + schema: + type: string + examples: + sample 1: + value: + topic: my-topic-name responses: "200": description: OK @@ -184,6 +195,17 @@ paths: sample 3: value: options: "(depth=2,fields=book/authors)" + - name: topic + in: query + description: topic parameter in query. + required: false + allowReserved: true + schema: + type: string + examples: + sample 1: + value: + topic: my-topic-name responses: "200": description: OK @@ -664,7 +686,7 @@ paths: schema: type: array items: - $ref: '#/components/schemas/ModuleReference' + $ref: '#/components/schemas/RestModuleReference' "400": description: Bad Request content: @@ -851,7 +873,7 @@ components: type: string details: type: string - ModuleReference: + RestModuleReference: title: Module reference details type: object properties: diff --git a/docs/deployment.rst b/docs/deployment.rst index 2f68a64ee1..3f5943ceb0 100644 --- a/docs/deployment.rst +++ b/docs/deployment.rst @@ -7,13 +7,13 @@ .. _deployment: CPS Deployment -============== +############## .. contents:: :depth: 2 CPS OOM Charts --------------- +============== The CPS kubernetes chart is located in the `OOM repository `_. This chart includes different cps components referred as further in the document are listed below: @@ -26,7 +26,8 @@ This chart includes different cps components referred as fu Please refer to the `OOM documentation `_ on how to install and deploy ONAP. Installing or Upgrading CPS Components --------------------------------------- +====================================== + The assumption is you have cloned the charts from the OOM repository into a local directory. **Step 1** Go to the cps charts and edit properties in values.yaml files to make any changes to particular cps component if required. @@ -91,7 +92,7 @@ After deploying cps, keep monitoring the cps pods until they come up. kubectl get pods -n | grep Restarting a faulty component ------------------------------ +============================= Each cps component can be restarted independently by issuing the following command: .. code-block:: bash @@ -102,7 +103,7 @@ Each cps component can be restarted independently by issuing the following comma .. _cps_common_credentials_retrieval: Credentials Retrieval ---------------------- +===================== Application and database credentials are kept in Kubernetes secrets. They are defined as external secrets in the values.yaml file to be used across different components as : diff --git a/docs/index.rst b/docs/index.rst index 62ba5e8b17..eaf36466f4 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,10 @@ .. _cps-framework-doc: CPS Documentation ------------------ +################# + +CPS Core +======== .. toctree:: :maxdepth: 1 @@ -22,12 +25,12 @@ CPS Documentation deployment.rst release-notes.rst -DMI-Plugin Documentation ------------------------- +DMI-Plugin +========== * :ref:`DMI-Plugin` -CPS-Temporal Documentation --------------------------- +CPS Temporal +============ * :ref:`CPS-Temporal` diff --git a/docs/overview.rst b/docs/overview.rst index 4b69dd8109..cde6f6db62 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -4,7 +4,7 @@ .. _overview: CPS Overview -============ +############ The Configuration Persistence Service (CPS) is a platform component that is designed to serve as a data repository for runtime data that needs persistence. @@ -28,10 +28,10 @@ Types of data that is stored: configuration and operational parameters depending on how they are used. CPS Components --------------- +============== CPS-Core -######## +-------- This is the component of CPS which encompasses the generic storage of Yang module data. **NCMP** @@ -43,13 +43,13 @@ NCMP accesses all network Data-Model-Inventory (DMI) information via NCMP-DMI-Pl even though CPS-Core could be deployed without the NCMP extension. NCMP-DMI-Plugin -#################### +--------------- The Data-Model-Inventory (DMI) Plugin is a rest interface used to synchronize CM-Handles data between CPS and DMI through the DMI-Plugin. This is built previously from the CPS-NF-Proxy component. CPS-Temporal -############ +------------ This service is responsible to provide a time oriented perspective for operational network data. It provides features to store and retrieve sequences @@ -57,14 +57,8 @@ of configurations or states along with the associated times when they occurred or have been observed. CPS Project ------------ - -Wiki: `Configuration Persistence Service Project `_ - -Contact Information -------------------- - -onap-discuss@lists.onap.org +=========== -Meeting details `Join `_ -`Agenda `_ +* Wiki: `Configuration Persistence Service Project `_ +* Contact Information: onap-discuss@lists.onap.org +* Meeting details: `Join `_ & `Agenda `_ diff --git a/docs/release-notes.rst b/docs/release-notes.rst index 0ca0547fad..c2e2a5fdcd 100755 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -5,11 +5,8 @@ .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING .. _release_notes: - - -================= CPS Release Notes -================= +################# .. contents:: :depth: 2 @@ -19,10 +16,25 @@ CPS Release Notes .. * * * JAKARTA * * * .. ======================== -Version: 3.0.0-SNAPSHOT -======================= +Version: 3.0.0 +============== + +Release Data +------------ -This section lists the main changes & fixes merged into master (snapshot) version of CPS-NCMP. This information is here to assist developers that want experiment/test using our latest code bases directly. Stability of this is not guaranteed. ++--------------------------------------+--------------------------------------------------------+ +| **CPS Project** | | +| | | ++--------------------------------------+--------------------------------------------------------+ +| **Docker images** | onap/cps-and-ncmp:3.0.0 | +| | | ++--------------------------------------+--------------------------------------------------------+ +| **Release designation** | 3.0.0 Jakarta | +| | | ++--------------------------------------+--------------------------------------------------------+ +| **Release date** | 2022 March 15 | +| | | ++--------------------------------------+--------------------------------------------------------+ Features -------- @@ -33,6 +45,8 @@ Features - `CPS-741 `_ Re sync after removing cm handles - `CPS-777 `_ Ensure all DMI operations use POST method - `CPS-780 `_ Add examples for parameters, request and response in openapi yaml for cps-core + - `CPS-789 `_ CPS Data Updated Event Schema V2 to support delete operation + - `CPS-791 `_ CPS-Core sends delete notification event - `CPS-817 `_ Create Endpoint For Get Cm Handles (incl. public properties) By Name - `CPS-837 `_ Add Remove and Update properties (DMI and Public) as part of CM Handle Registration update -- cgit 1.2.3-korg