Date: | Author: | Version: | Changes: | Completed | Ext. | Int. | Is in Core | Jira Ref. |
|---|---|---|---|---|---|---|---|---|
0.1 | Doc. created | Yes/No | x |
| N/A |
| ||
| 14/04-2016 | Anders Granau Høfft | 0.2 | Sections expanded | No | x | N/A | CDRRM-733 | |
| 11 May 2016 | Emil Ifrim | 0.3 | Database configuration | No | x | N/A | ||
| 20 March 2017 | Emil Ifrim | 0.4 | Redesign Update | No | x | N/A | ||
| 01 April 2018 | Emil Ifrim | 0.5 | Redesign Update | No | x | N/A |
...
This is a brief guide on how to install the REST service (rator-selfcare-rest-api project and rator-rest-api-auth project). A customer rest project involves deploying three artifacts:
...
This section is about how to modify the customer project's pom so as to include the selfcarerator-rest-api in the build.
Note
...
| Info |
|---|
This section describes installation of the core services. For a customer setup, an additional war has to be deployed (the one containing the customized REST services) |
- Retrieve the
rator-selfcare-rest-api.war file (either from Jenkins/Nexus, see Resources, or by building the .war yourself, see Build). - Retrieve the
rator-rest-api-auth.war file (either from Jenkins/Nexus, see Resources, or by building the .war yourself, see Build). - Copy the war files to the Tomcat webapps directory and (re-)start the Tomcat application.
- Retrieve the swagger-ui
distfolder (either from Github, or from our own repositories, see Resources. Or by building the project yourself, see Build). - Copy the dist folder to the Tomcat
webappsdirectory and (re-)start the Tomcat application. You probably want to rename thedistfolder toswagger-ui.- Nb This can be a different Tomcat installation than in step 2, or the same.
- 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.
In order to access secure resources through swagger-ui, two one additional parameters parameter must be configured in the Properties.txt file:
Code Block language sql title oauth2 selfcare client rest.api.accessTokenUri=http://<host>:<port/<auth-app-context>/oauth/token #example: http://10.45.1.81:8081/rator-rest-api-auth/oauth/token rest.api.userAuthorizationUri=http://<host>:<port/<auth-app-context>/oauth/authorize #example: http://10.45.1.81:8081/rator-rest-api-auth/oauth/authorize
| Compatibility matrix | |
| rator-selfcare-rest-ap | Swagger UI |
|---|---|
| 1.0 | 2.1.1 |
...
- Run table_changes.sql
Configure REST api clients - who is allowed to get security tokens in order to access resources that require authentication/authorization. Here are some examples:
Code Block language sql title oauth2 selfcare client Insert into OAUTH_CLIENT_DETAILS (CLIENT_ID, CLIENT_SECRET, SCOPE, AUTHORIZED_GRANT_TYPES, ACCESS_TOKEN_VALIDITY, REFRESH_TOKEN_VALIDITY, AUTHORITIES) Values ('rator-selfcare-web-app', 'ratorselfcare', 'read,write', 'password', 600, 0);, 'ACCESS_BRAND_brandKey'); --replace brandKey with a valid brand in the setup
Note: Swagger-ui client should only be used in development environments!
Code Block title oauth2 swagger-ui client Insert into OAUTH_CLIENT_DETAILS (CLIENT_ID, CLIENT_SECRET, SCOPE, AUTHORIZED_GRANT_TYPES, ACCESS_TOKEN_VALIDITY, AUTOAPPROVE, AUTHORITIES) Values ('your-client-id', 'your-client-secret', 'read-write:api-doc', 'implicitpassword,operator_password,client_credentials', 600, 'true', 'ACCESS_BRAND_brandKey'); --replace brandKey with a valid brand in the setup
Verify deployment
In your browser, enter the URL:
...
| Code Block |
|---|
http://localhost:8080/swagger-ui/?url=http://localhost:8080/rator-selfcare-rest-api-bootstrap/api/swagger.json |
If you get an error response from the server, try pin pointing the problem:
...
| Code Block |
|---|
<Context antiJARLocking="true" docBase="C:\Program Files\Tomcat\apache-tomcat-7.0.54\webapps\rator-selfcare-rest-api-bootstrap" path="" reloadable="true" source="org.eclipse.jst.jee.server:rator-selfcare-rest-api"/> |
If the Tomcat's server.xml file had a <Context/> tag like the above, where the base path for the rator-selfcare-rest-api-botstrap is set to the empty string, the project would be available at http://localhost:8080/api/<SOME RESOURCE>.
...
The artifacts to deploy (the REST application and Swagger UI) can either be produced manually from source code (see below - Installation guide), downloaded from Nexus, or retrieved from Jenkins.
SVN
- https://svnbitbucket.cdrator.com/svn/dev/uiorg/cdrator/rator-selfcare-rest-api
- https://svnbitbucket.cdrator.com/svn/dev/uiorg/cdrator/rator-rest-api-auth
- https://svnbitbucket.cdrator.com/svn/devorg/cdrator/rator-core-api/
- https://svn.cdrator.com/svn/dev/thirdparty/swagger-ui
...
Jobs are set up to do continuous integration. The artifacts produced from a build are placed in the given job's "Workspace" (Arbejdsområde) page, in the folder "target":
Nexus
Our Jenkins jobs are configured to deploy to Nexus. On Nexus, you can find both the source code and the artifacts produced from the build.
...
For information about how to include the selfcarerator-rest-api project in the customer project's build, see the section 'How to include the REST api in customer projects'.
...
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.
rator
...
-rest-api
- Check out the source code (See the
Resourcesparagraph above) - Create the artifact:
mvn clean package You should now have arator-selfcare-rest-api-bootstrap-<version>.warfile in the target folder.
...