From: Toine Siebelink Date: Mon, 16 Oct 2023 16:11:21 +0000 (+0000) Subject: Merge "Add NCMP Stub documentation to RTD" X-Git-Tag: 3.3.9~17 X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=263bde5fc28bf26982e94aaaf827865139a1868f;hp=624f04c03146e002bab2ca88e55b7f586c6e1aff;p=cps.git Merge "Add NCMP Stub documentation to RTD" --- diff --git a/.gitignore b/.gitignore index b4abc48bc7..c59fc4731d 100755 --- a/.gitignore +++ b/.gitignore @@ -27,10 +27,10 @@ tmp/ .checkstyle /.tox -/_build/* /__pycache__/* /docs/docs/ /docs/.vscode/ +/docs/_build/* /test-tools/metrics-reports/ diff --git a/docs/cps-path.rst b/docs/cps-path.rst index 6611789544..eb203d8918 100644 --- a/docs/cps-path.rst +++ b/docs/cps-path.rst @@ -247,7 +247,7 @@ leaf-conditions - Using comparative operators with string values will lead to an error at runtime. This error can't be validated earlier as the datatype is unknown until the execution phase. - The key should be supplied with correct data type for it to be queried from DB. In the last example above the attribute code is of type Integer so the cps query will not work if the value is passed as string. - eg: ``//categories[@code="1"]`` or ``//categories[@code='1']`` will not work because the key attribute code is treated a string. + e.g.: ``//categories[@code="1"]`` or ``//categories[@code='1']`` will not work because the key attribute code is treated a string. **Notes** - For performance reasons it does not make sense to query using key leaf as attribute. If the key value is known it is better to execute a get request with the complete xpath. @@ -260,7 +260,7 @@ The text()-condition can be added to any CPS path query. **Syntax**: `` ( '/' '[text()=' ']' )?`` - ``cps-path``: Any CPS path query. - ``leaf-name``: The name of the leaf or leaf-list which value needs to be compared. - - ``string-value``: The required value of the leaf or leaf-list element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This wil still match integer values. + - ``string-value``: The required value of the leaf or leaf-list element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This will still match integer values. **Examples** - ``//book/label[text()="classic"]`` diff --git a/docs/cps-stubs.rst b/docs/cps-stubs.rst new file mode 100644 index 0000000000..e41fe174ec --- /dev/null +++ b/docs/cps-stubs.rst @@ -0,0 +1,33 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2023 Nordix Foundation + +.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING + +.. _cpsStubs: + + +CPS Stubs +######### + +.. toctree:: + :maxdepth: 1 + +Currently stubs are only provided for the CPS-NCMP interface. + +Prerequisites +============= +t.b.d. + +Method 1: Running Stubs as an Application +========================================= +t.b.d. + +Method 2: Using Stubs in Unit Tests +=================================== +t.b.d. + + +NCMP Stubs +========== +t.b.d. diff --git a/docs/deployment.rst b/docs/deployment.rst index 0642e6a8e1..0fee55969a 100644 --- a/docs/deployment.rst +++ b/docs/deployment.rst @@ -197,8 +197,8 @@ Any spring supported property can be configured by providing in ``config.additio | logging.level | Logging level set in cps-core | info | | | | | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ -| config.useStrimziKafka | If targeting a custom kafka cluster, ie useStrimziKafka: false, the config.eventPublisher.spring.kafka | true | -| | values below must be set. | | +| config.useStrimziKafka | If targeting a custom kafka cluster, i.e. useStrimziKafka: false, the | true | +| | config.eventPublisher.spring.kafka values below must be set. | | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ | config.eventPublisher. | Kafka hostname and port | ``:9092`` | | spring.kafka.bootstrap-servers | | | diff --git a/docs/design.rst b/docs/design.rst index 5ad86a3aed..80eb5f1523 100755 --- a/docs/design.rst +++ b/docs/design.rst @@ -1,6 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2021-2022 Nordix Foundation +.. Copyright (C) 2021-2023 Nordix Foundation .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING .. _design: @@ -93,3 +93,24 @@ NCMP uses common responses codes in REST responses and events. Also the DMI plug :maxdepth: 1 cps-ncmp-message-status-codes.rst + +Contract Testing (stubs) +======================== + +The CPS team is committed to supporting consumers of our APIs through contract testing. +Obviously we test our own contracts on a continuous basis as part of the build and delivery process. +CPS uses a contract-first approach. That means we write our OpenAPi contracts first and then generate the interface code from that. +This means our interface implementation simply cannot deviate from the OpenApi contracts we deliver. + +Another advantage is that we can also generate 'stubs'. Stubs are a basic implementation of the same interface for testing purposes. +These stubs can be used by clients for unit testing but also for more higher level integration-like testing where the real service is replaced by a stub. +This can be useful for faster feedback loops where deployment of a full stack is difficult and not strictly needed for the purpose of the tests. + +Stubs for contract testing typically always return the same response which is sufficient for the strict definition of a contract test. +However it is often useful to allow more variation in the responses so different clients or the same client can test different scenarios without having to mock the service. +CPS has implemented what we call 'extended stubs' that allow clients to provide alternate responses.implementation + +The available stubs and how to use them are described in :doc:'cps-stubs'. + + + diff --git a/docs/index.rst b/docs/index.rst index c1427ad381..573bd54122 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,6 +25,7 @@ CPS cps-events.rst deployment.rst release-notes.rst + cps-stubs.rst DMI-Plugin ========== diff --git a/docs/release-notes.rst b/docs/release-notes.rst index d891162c32..e6b81fcbaf 100755 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -515,7 +515,7 @@ Bug Fixes - `CPS-1289 `_ Getting wrong error code for create node api - `CPS-1326 `_ Creation of DataNodeBuilder with module name prefix is very slow - `CPS-1344 `_ Top level container (prefix) is not always the first module - - `CPS-1350 `_ Add Basic Auth to CPS/NCMP OpenAPI Definitions. + - `CPS-1350 `_ Add Basic Authentication to CPS/NCMP OpenAPI Definitions. - `CPS-1352 `_ Handle YangChoiceNode in right format. - `CPS-1409 `_ Fix Delete uses case with '/' in path. - `CPS-1433 `_ Fix to allow posting data with '/' key fields. @@ -701,7 +701,7 @@ Bug Fixes - `CPS-957 `_ NCMP: fix getResourceDataForPassthroughOperational endpoint - `CPS-1020 `_ DuplicatedYangResourceException error at parallel cmHandle registration - `CPS-1056 `_ Wrong error response format in case of Dmi plugin error - - `CPS-1067 `_ NCMP returns 500 error on searches endpoint when No DMi Handles registered + - `CPS-1067 `_ NCMP returns 500 error on searches endpoint when No DMI Handles registered - `CPS-1085 `_ Performance degradation on ncmp/v1/ch/searches endpoint - `CPS-1088 `_ Kafka consumer can not be turned off - `CPS-1097 `_ Unable to change state from LOCKED to ADVISED @@ -813,7 +813,7 @@ Bug Fixes - `CPS-886 `_ Fragment handling decreasing performance for large number of cmHandles - `CPS-887 `_ Increase performance of cmHandle registration for large number of schema sets in DB - `CPS-892 `_ Fixed the response code during CM-Handle Registration from 201 CREATED to 204 NO_CONTENT - - `CPS-893 `_ NCMP Java API depends on NCM-Rest-API (cyclic) through json properties on Java API + - `CPS-893 `_ NCMP Java API depends on NCMP-Rest-API (cyclic) through json properties on Java API Known Limitations, Issues and Workarounds ----------------------------------------- @@ -1268,7 +1268,7 @@ Security Notes *Known Security Issues* - * Weak Crytography using md5 + * Weak Cryptography using md5 * Risk seen in Zip file expansion *Known Vulnerabilities in Used Modules* diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt new file mode 100644 index 0000000000..3bfa9a0a31 --- /dev/null +++ b/docs/spelling_wordlist.txt @@ -0,0 +1,67 @@ +api +async +authorization +boolean +behavior +camelCasing +cmHandle +cmHandles +config +color +cps +cpsPath +cpsPaths +csit +customizations +dataschema +dataspace +dataspaces +datasource +datastore +datastores +deliverables +dmi +dmiPlugin +dmiPlugins +rnv +hazelcast +hostname +jira +json +kafka +kibana +kubernetes +kohn +lifecycle +liquibase +logback +modeled +modeling +normalized +ncmp +onap +openapi +optimized +passthrough +performant +postgres +queryable +repo +runtime +schemas +sql +ssl +standardized +synchronize +synchronization +undeploying +utilizes +xml +xNF +xNFs +xpath +xpaths +xPath +XPath +XPaths +yaml \ No newline at end of file diff --git a/docs/tox.ini b/docs/tox.ini index 8684276f97..7020752c8c 100644 --- a/docs/tox.ini +++ b/docs/tox.ini @@ -21,23 +21,23 @@ minversion = 1.6 envlist = docs,docs-linkcheck,docs-spellcheck skipsdist = true [testenv:docs] -basepython = python3.8 +basepython = python3.10 deps = -r{toxinidir}/requirements-docs.txt -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master commands = - sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html + sphinx-build -q -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html [testenv:docs-linkcheck] -basepython = python3.8 +basepython = python3.10 deps = -r{toxinidir}/requirements-docs.txt -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master commands = - sphinx-build -W -q -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck + sphinx-build -q -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck [testenv:docs-spellcheck] -basepython = python3.8 +basepython = python3.10 deps = -r{toxinidir}/requirements-docs.txt -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt