summaryrefslogtreecommitdiffstats
path: root/docs/development
diff options
context:
space:
mode:
authorLiam Fallon <liam.fallon@est.tech>2021-07-20 11:55:15 +0000
committerGerrit Code Review <gerrit@onap.org>2021-07-20 11:55:15 +0000
commit8bd2403907becf8a6d246408434fbceaa30ba745 (patch)
tree258ebff1647b7d9e820fbd359148236402cbae8a /docs/development
parent561c0a8f068a246438509058f8ecf080751e6b83 (diff)
parent123321473628cbacd35963f4f30bf2ab621fd3b7 (diff)
Merge "Add profile for generating Swagger documents"
Diffstat (limited to 'docs/development')
-rw-r--r--docs/development/devtools/devtools.rst49
1 files changed, 49 insertions, 0 deletions
diff --git a/docs/development/devtools/devtools.rst b/docs/development/devtools/devtools.rst
index 1e2fd49f..7eb5e064 100644
--- a/docs/development/devtools/devtools.rst
+++ b/docs/development/devtools/devtools.rst
@@ -283,3 +283,52 @@ familiar with the Policy Framework components and test any local changes.
xacml-s3p.rst
distribution-s3p.rst
+Generating Swagger Documentation
+********************************
+The `Policy Parent Integration POM <https://github.com/onap/policy-parent/blob/master/integration/pom.xml>`_ contains a *generateSwaggerDocs* profile. This
+profile can be activated on any module that has a Swagger endopint. When active, this profile creates a tarball in Nexus with the name
+*<project-artifactId>-swagger-docs.tar.gz*. The tarball contains the fillowing files:
+
+.. code-block:: bash
+
+ swagger/swagger.html
+ swagger/swagger.json
+ swagger/swagger.pdf
+
+The profile is activated when:
+
+1. The following property is defined at the top of the *pom.xml* file for a module
+
+ .. code-block:: bash
+
+ <!-- This property triggers generation of the Swagger documents -->
+ <swagger.generation.phase>post-integration-test</swagger.generation.phase>
+
+ See the `CLAMP runtime POM <https://github.com/onap/policy-clamp/blob/master/runtime/pom.xml>`_ for an example of the usage of this property.
+
+2. Unit tests are being executed in the build, in other wirds when the *skipTests* flag is *false*.
+
+You **must** create a unit test in your module that generates the following file:
+
+.. code-block:: bash
+
+ src/test/resources/swagger/swagger.json
+
+Typically, you do this by starting your REST endpoint in a unit test, issuing a REST call to get the Swagger API documentation. The test case below is an example
+of such a test case.
+
+.. code-block:: java
+
+ @Test
+ public void testSwaggerJson() throws Exception {
+ ResponseEntity<String> httpsEntity = getRestTemplate()
+ .getForEntity("https://localhost:" + this.httpsPort + "/restservices/clds/api-doc", String.class);
+ assertThat(httpsEntity.getStatusCode()).isEqualTo(HttpStatus.OK);
+ assertThat(httpsEntity.getBody()).contains("swagger");
+ FileUtils.writeStringToFile(new File("target/swagger/swagger.json"), httpsEntity.getBody(),
+ Charset.defaultCharset());
+ }
+
+See `this unit test case <https://github.com/onap/policy-clamp/blob/master/runtime/src/test/java/org/onap/policy/clamp/clds/it/HttpsItCase.java>`_
+for the full example.
+