Page Comparison

...

A Tomcat must be installed on your environment. Please ensure to get Tomcat 7 our core functionality do not support future versions.

Short installation guide

1. Download the REST web app: http://cdrsrvbuild2:8080/jenkins/job/rator-selfcare-rest-API-TRUNK/ws/target/rator-selfcare-rest-api-0.0.1-SNAPSHOT.war
2. Copy the war file to the Tomcat webapps directory and (re-)start the Tomcat application.
3. Download the Swagger UI documentation web servce: TODO
4. Copy the .dist folder to the <Tomcat root>/webapps/swagger-ui directory and (re-)start the Tomcat application. Nb This can be a different Tomcat installation than in step 2, or the same. TODO: Verify this
5. In your browser, enter URL "http://<Swagger server and port>/swagger-ui/?url=http://<REST server and port>/api/swagger.json"

NB Your Tomcat installation's server.xml file will specify a base path for the REST project. The base path is the part of the URL to the REST web app, or any other, that immediately follows the <REST server and port>, but before the /api/ which is part of the resource paths specified in the REST project's source code. 

If step 6 does not work, you must either modify the base path, or modify the URL accordingly. If you are deploying from Eclipse, you will want to specify the base path on the modules subpane of the server pane. The URL in step 6 assumes a <context/> entry a la the following ( - notice the empty string in the path parameter): 

Resources

Source code is available both in our SVN repository, in Jenkins and in Nexus (where our Jenkins build deploys to).

...

Jobs are set up to do continuous integration. The artifacts produced from a build are placed in given the job's "Workspace" (Arbejdsområde) page, in the folder "target":

• http://cdrsrvbuild2:8080/jenkins/job/rator-selfcare-rest-API-TRUNK/ws/target/rator-selfcare-rest-api-0.0.1-SNAPSHOT.war

Nexus

Our Jenkins jobs are configured to deploy to Nexus. There, you can find both the source code and the artifacts produced from the build.

...

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. Download the Swagger UI documentation web servce: TODO
4. Navigate to your Tomcat installation's <Tomcat root>/webapps/ folder and create a directory called swagger-ui. 

...

...

1. Copy the content of the dist folder into your new swagger-ui folder and (re-)start the Tomcat application. Nb This can be a different Tomcat installation than in step 2, or the same.
2. In your browser, enter the URL "http://<Swagger server and port>/<base-path>/?url=http://<REST server and port>/<base-path>/api/swagger.json". You should now see a list of the resources available on the REST server.

If both the Swagger UI and the REST application has been deployed to the same Tomcat, and if Tomcat's default "base path to web-app configuration" has not been overwritten, the URL to call may look like this:

http://localhost:8080/swagger-ui/?url=http://localhost:8080/rator-selfcare-rest-api/api/swagger.json

Verify installation

In your browser, enter the URL ":

http://<Swagger server and port>/

...

<base-

...

path>/?url=http://<REST server and port>/<base-path>/api/swagger.json

...

(If you have installed the REST web app and the Swagger UI on the same Tomcat, <Swagger server and port> will be the same as <REST server and port>.)

...

You should now see a list of the resources available on the REST server.

If both the Swagger UI and the REST application has been deployed to the same Tomcat, and if Tomcat's default "base path to web-app configuration" has not been overwritten, the URL to call may look like this: 

http://localhost:8080/swagger-ui/?url=http://localhost:8080/rator-selfcare-rest-api/api/swagger.json

If you get an error response from the server, try pin pointing the problem:

1. Verify that the Swagger UI service is available: Enter http://<Swagger server and port>/<base-path> in a browser. <base-path> will by "swagger-ui" unless default Tomcat behavior has been modified. If you get a 404 server error, see step 3.
2. Verify that the rator-selfcare-rest-api is available: Enter http://<REST server and port>/<base-path>. This should show you the index.html page, which is (currently) a (very) short text stating that you have reached the RESTful webservice.  If you get a 404 error response from the server, see step 3.
3. Tomcat maps "base paths" to the web apps in your Tomcats WEBAPP folder. The is called the context. Unless you specify otherwise, the base path is the name of the given web application's main folder. If you get a 404 error response from the server, you should investigate if Tomcat's default base path/context configuration has been overwritten, and with which values. This is general Tomcat configuration, and as such outside the scope of this documentation.

A brief remark on Tomcat's base path:

Your Tomcat installation's server.xml file will sometimes specify a base path for the REST project in a <context.../> tag.

<Context antiJARLocking="true" docBase="C:\Program Files\Tomcat\apache-tomcat-7.0.54\webapps\rator-selfcare-rest-api" path="" reloadable="true" source="org.eclipse.jst.jee.server:rator-selfcare-rest-api"/>

When deploying from Eclipse, such entry might have been added automatically. Configuring the context in the server.xml seems to be discouraged by various online sources.  

If 404 errors are returned from the server, when accessing the deployed services, you must either modify the base path, or modify the URL accordingly. If you are deploying from Eclipse, you may want to specify the base path on the modules subpane of the server pane.