Page Comparison

...

The document also describes how to deploy the third-party documentation service called Swagger UI. This is not required for the REST service to work, but provides useful documentation.

How to include the REST api in customer projects

This section is about how to modify the customer project's pom so as to include the selfcare-rest-api in the build.

You will need to create a new pom and put it in a subfolder of your customer project. Follow these steps:

1. Create a customer REST API module, i.e. a "wrapper pom" that specifies dependencies to A) rator-selfcare-rest-api and B) customer core branch containing customized logic.
   
2. Optional: Add a build section to the newly created pom wherein an alternative output directory is specified for the war + an alternative name.
3. Add the pom to a subfolder of the folder containing the projects main pom.
4. Add a reference to the created module in a module tag in the projects main pom. Fx: <module>OisterREST/oister-selfcare-rest-api</module> where the folder 'oister-selfcare-rest-api' contains the pom.
5. In a terminal, navigate to the folder of the project's main pom and type 'mvn package'. Verify that the expected wars and jars are created, among other the selfcare-rest-api.war.

Customer REST-api pom example

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
		 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>com.cdrator.projects.oister</groupId>
    <artifactId>oister-project</artifactId>
    <version>16.01</version>
    <relativePath>../../pom.xml</relativePath>
  </parent>

  <artifactId>oister-selfcare-rest-api</artifactId>
  <packaging>war</packaging>
  <name>Oister REST API Module</name>
  <description>Oister REST API Module Code</description>
  
  <!-- Dependencies for this module. -->
  <dependencies>
	<dependency>
		<groupId>${project.groupId}</groupId>
		<artifactId>oister-billing</artifactId>
		<version>${project.version}</version>
		<scope>runtime</scope>
	</dependency>
	<dependency>
		<groupId>com.cdrator</groupId>
		<artifactId>rator-selfcare-rest-api</artifactId>
		<version>0.0.1-SNAPSHOT</version>
		<scope>runtime</scope>
		<type>war</type>
	</dependency>
</dependencies>
  
  <build>
    <finalName>REST-api</finalName>
    <plugins>
      <plugin>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <outputDirectory>${project.parent.build.directory}</outputDirectory>
        </configuration>
      </plugin>
      <plugin>
        <groupId>com.cdrator.maven.plugins</groupId>
        <artifactId>rator-maven-renamer-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

If the 'oister-selfcare-rest-api' pom above resides in a '/OisterREST/oister-selfcare-rest-api' [relative to customer project's main pom] the we need to add the following to the Oister project's pom: <module>OisterREST/oister-selfcare-rest-api</module>.

Now, when building the project, we also get the selfcare-rest-api war file constructed (and placed in the main target folder and named REST-api.war).

Install Tomcat 7

A Tomcat must be installed on your environment. 

...

1. Retrieve the rator-selfcare-rest-api .war file (either from Jenkins/Nexus, see Resources, or by building the .war yourself, see Build).
2. Copy the war file to the Tomcat webapps directory and (re-)start the Tomcat application.
3. Retrieve the swagger-ui dist folder (either from Github, or from our own repositories, see Resources. Or by building the project yourself, see Build).
4. Copy the dist folder to the Tomcat webapps directory and (re-)start the Tomcat application. You probably want to rename the dist folder to swagger-ui. 
   1. Nb This can be a different Tomcat installation than in step 2, or the same.
5. In your browser, enter the URL "http://<Swagger server and port>/<base-path>/?url=http://<REST server and port>/<base-path>/api/swagger.json". 
6. You should now see a list of the resources available on the REST server.

...

• http://cdrsrvbuild:8081/nexus/index.html

Build

This paragraph contains information about how to "manually" build the referenced projects from terminal (Mostly of interest to developers).

For information about how to include the selfcare-rest-api project in the customer project's build, see the paragraph Customer project configuration.

You can build the artifacts yourself. Notice that the Swagger UI is not a Java project, for which reason its build procedure is different than the REST application.

...