This article explains how to build the ONAP Policy Framework for development purposes and how to run stability/performance tests for a variety of components. To start, the developer should consult the latest ONAP Wiki to familiarize themselves with developer best practices and how-tos to setup their environment, see `https://wiki.onap.org/display/DW/Developer+Best+Practices`.
-
This article assumes that:
* You are using a *\*nix* operating system such as linux or macOS.
Generating Swagger Documentation
********************************
-1. Using Swagger2Markup maven plugin from Policy Parent Integration POM
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-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 endpoint. When active, this profile creates a tarball in Nexus with the name
-*<project-artifactId>-swagger-docs.tar.gz*. The tarball contains the following 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 words 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());
- }
-
-2. Accessing Swagger documentation for springboot based policy applications
+1. Accessing Swagger documentation for springboot based policy applications
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Springfox Swagger2 maven dependency aids with auto-generation of Swagger documentation.
</pluginManagement>
</build>
</profile>
- <profile>
- <id>generateSwaggerDocs</id>
- <activation>
- <property>
- <name>!skipTests</name>
- </property>
- </activation>
- <build>
- <plugins>
- <!-- Read the swagger.json file and the definition from SwaggerConfig.java; generate
- a list of .adoc files containing the APIs info in more structured way -->
- <plugin>
- <groupId>io.github.swagger2markup</groupId>
- <artifactId>swagger2markup-maven-plugin</artifactId>
- <version>1.3.3</version>
- <dependencies>
- <dependency>
- <groupId>io.github.swagger2markup</groupId>
- <artifactId>swagger2markup-import-files-ext</artifactId>
- <version>1.3.3</version>
- </dependency>
- <dependency>
- <groupId>io.github.swagger2markup</groupId>
- <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
- <version>1.3.3</version>
- </dependency>
- </dependencies>
- <configuration>
- <swaggerInput>${project.build.directory}/swagger/swagger.json</swaggerInput>
- <outputDir>${project.build.directory}/asciidoc/generated</outputDir>
- <config>
- <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
- </config>
- </configuration>
- <executions>
- <execution>
- <phase>${swagger.generation.phase}</phase>
- <goals>
- <goal>convertSwagger2markup</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
-
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-dependency-plugin</artifactId>
- <executions>
- <execution>
- <id>unpack-swagger-asciidoc</id>
- <phase>${swagger.generation.phase}</phase>
- <goals>
- <goal>unpack</goal>
- </goals>
- <configuration>
- <artifactItems>
- <artifactItem>
- <groupId>org.onap.policy.parent</groupId>
- <artifactId>policy-parent-resources</artifactId>
- <type>jar</type>
- <overWrite>true</overWrite>
- <outputDirectory>${project.build.directory}</outputDirectory>
- </artifactItem>
- </artifactItems>
- <includes>asciidoc/**</includes>
- <outputDirectory>${project.build.directory}</outputDirectory>
- </configuration>
- </execution>
- </executions>
- </plugin>
-
- <!-- Run the generated asciidoc through Asciidoctor to generate other documentation
- types, such as PDFs or HTML5 -->
- <plugin>
- <groupId>org.asciidoctor</groupId>
- <artifactId>asciidoctor-maven-plugin</artifactId>
- <version>1.5.7.1</version>
- <dependencies>
- <dependency>
- <groupId>org.asciidoctor</groupId>
- <artifactId>asciidoctorj-pdf</artifactId>
- <version>1.5.0-alpha.10.1</version>
- </dependency>
- </dependencies>
- <configuration>
- <sourceDirectory>${project.build.directory}/asciidoc</sourceDirectory>
- <sourceDocumentName>swagger.adoc</sourceDocumentName>
- <attributes>
- <doctype>book</doctype>
- <toc>left</toc>
- <toclevels>3</toclevels>
- <numbered />
- <hardbreaks />
- <sectlinks />
- <sectanchors />
- <generated>${project.build.directory}/asciidoc/generated</generated>
- </attributes>
- </configuration>
-
- <executions>
- <execution>
- <id>output-html</id>
- <phase>${swagger.generation.phase}</phase>
- <goals>
- <goal>process-asciidoc</goal>
- </goals>
- <configuration>
- <backend>html5</backend>
- <outputDirectory>${project.build.directory}/swagger</outputDirectory>
- </configuration>
- </execution>
- <execution>
- <id>output-pdf</id>
- <phase>${swagger.generation.phase}</phase>
- <goals>
- <goal>process-asciidoc</goal>
- </goals>
- <configuration>
- <backend>pdf</backend>
- <outputDirectory>${project.build.directory}/swagger</outputDirectory>
- </configuration>
- </execution>
- </executions>
- </plugin>
-
- <!-- Create a tarball for Swagger documents -->
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-assembly-plugin</artifactId>
- <dependencies>
- <dependency>
- <groupId>org.onap.policy.parent</groupId>
- <artifactId>policy-parent-resources</artifactId>
- <version>${version.parent.resources}</version>
- </dependency>
- </dependencies>
- <executions>
- <execution>
- <id>generate-swagger-tar</id>
- <phase>${swagger.generation.phase}</phase>
- <goals>
- <goal>single</goal>
- </goals>
- <configuration>
- <descriptorRefs>
- <descriptorRef>swagger-docs</descriptorRef>
- </descriptorRefs>
- <finalName>${project.artifactId}</finalName>
- </configuration>
- </execution>
- </executions>
- </plugin>
-
- </plugins>
- </build>
- </profile>
</profiles>
<build>
Code Review / policy / parent.git / commitdiff