Boat Bay allows for the management of products specs. This documentation will explain how to configure the application and how to use it effectively.
The bootstrap file loads the configured sources when you run the application. It specifies the following:
- The sources your specs come from.
- How to search the sources for specs.
- How to process the specs.
- Portal definitions.
- Portal rule configurations.
Start by creating a bootstrap.yaml file. This will
most likely be located in a with the specifications
that are to be used with Boat Bay.
The following example shows a typical bootstrap.yaml configuration, with definitions for portals, sources, dashboard
and specTypes:
portals:
- key: "repo"
name: "repo.example.com"
lintRules:
- ruleId: 150
- ruleId: B001
- ruleId: B002
- ruleId: B003
- ruleId: B004
- ruleId: B005
- ruleId: B006
- ruleId: B007
- ruleId: B008
- ruleId: B009
- ruleId: B010
- ruleId: M0012
sources:
- name: repo.example.com - PetStore
baseUrl: https://repo.example.com/
type: FILESYSTEM
active: true
filterArtifactsName: "*.yaml"
sourcePaths:
- name: /petstore/
username: {username}
password: {password}
cronExpression: 0 0 13 * * *
capabilityKeySpEL: sourcePath.substring(0, sourcePath.indexOf('/'))
capabilityNameSpEL: sourcePath.substring(0, sourcePath.indexOf('/'))
serviceKeySpEL: sourceName.substring(0, sourceName.lastIndexOf('-')).replaceAll('-([a-z]*?)-api', '').replaceAll('-integration([-a-z]*)', '')
serviceNameSpEL: sourceName.substring(0, sourceName.lastIndexOf('-')).replaceAll('-([a-z]*?)-api', '').replaceAll('-integration([-a-z]*)', '')
specKeySpEL: sourceName.substring(0, sourceName.lastIndexOf('-'))
specFilterSpEL: sourcePath.contains('common-types') || sourcePath.substring(1, sourcePath.indexOf('/', 1)).contains('integration') || sourcePath.substring(1, sourcePath.indexOf('/', 1)).contains('persistence')
productReleaseKeySpEL: info.name.replaceAll('-api.zip', '')
productReleaseVersionSpEL: info.name.replaceAll('banking-services-bom-', '').replaceAll('-api.zip', '')
productReleaseNameSpEL: info.name.replaceAll('-api.zip', '')
overwriteChanges: false
runOnStartup: true
itemLimit: 5
portal:
key: "repo"
product:
key: "pet-store"
name: "Pet Store"
jiraProjectId: 23098
dashboard:
name: OpenAPI Quality Dashboard
defaultPortal:
key: "repo"
specTypes:
- name: Client API
matchSpEL: sourceName.contains('client-api')
icon: public
- name: Service API
matchSpEL: sourceName.contains('service-api')
icon: public_off
- name: Integration Inbound
matchSpEL: sourceName.contains('inbound')
icon: input
- name: Integration Outbound
matchSpEL: sourceName.contains('outbound')
icon: outbound
- name: Integration Pull
matchSpEL: sourceName.contains('pull')
icon: swap_vert
- name: Integration
matchSpEL: sourceName.contains('integration-api')
icon: import_export
- name: Persistence
matchSpEL: sourceName.contains('persistence') || sourceName.contains('pandp')
icon: storage
Replace {username} and {password} with your own repo credentials.
The fields in the source section are as follows:
name: the name of your sourcebaseUrl: the base URL that will be used for your specstype: describes where your source comes from: file system, jfrog, or Boat Maven pluginactive: boolean indicating state of activityfilterArtifactsName: filters the artifacts you wish to scan for specs, for example, what type of file ending, yaml, json, yml -sourcePaths: a list of the parent directories for each capability under the product defined in this sourcename: /{capability_name}/username: the username of the user accessing the repo. This can change depending on the repo configured for this source.password: the password of the user accessing the repo. This is the password/key you use to access the repo configured in the source. Typically encrypted.cronExpression: schedule for scanning the source for updates and changescapabilityKeySpEL: Spring Expression Language (SpEL) expression to generate capability namescapabilityNameSpEL: SpEL expression to generate the capability namesserviceKeySpEL: SpEL expression to generate the service keysserviceNameSpEL: SpEL expression to generate the service namesspecFilterSpEL: SpEL expression to filtering specificationsspecKeySpEL: SpEL expression to generating the spec keysoverwriteChanges:boolean,if set totruethen overwrites changes to existing specs, iffalsea new spec is createdrunOnStartup:boolean, if set totruethen specs are scanned from this source upon starting the applicationportal:key: key for this source's portalname: name for this source's portal
productkey: key for this productname: name for this product
Define the portals used in the sources where indicated in the example.
Run mvn clean install in project root.
It is likely that some heap space issues will arise, in this case increase memory size.
To run the application add the following parameters to your run configuration :
- name:
backbase.bootstrap.filevalue: location of the bootstrap.yaml file described in Bootstrap File. - name:
boat.scheduler.source.scanner.enabled value:true
To find out how to run front end go to boat-bay-frontend.
Add the following properties to your run configuration:
- spring.liquibase.clear-checksums
- spring.liquibase.drop-first
Set both to true and select them during run when you wish to reset the database.
A spec can be uploaded through boat-maven-plugin.
Before a spec can be uploaded a source must be set-up. This
can be done as shown in the Bootstrap file section.
The plugin configuration will look like example below:
<build>
<plugins>
<plugin>
<groupId>com.backbase.oss</groupId>
<artifactId>boat-maven-plugin</artifactId>
<executions>
<execution>
<id>lint</id>
<phase>validate</phase>
<goals>
<goal>lint</goal>
</goals>
<configuration>
<boatBayServerUrl>${url}</boatBayServerUrl>
<inputSpec>${project.basedir}/src/main/resources/petstore.yaml</inputSpec>
<output>${project.basedir}/src/main/resources/output</output>
<sourceKey>sourceKey</sourceKey>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>For the spec to be uploaded to Boat Bay configuration of the Boat Bay's server URL is required. To configure the URL, either:
- configure it in the plugin as shown above
- set it as the environment variable BOAT_BAY_SERVER_URL by running export BOAT_BAY_SERVER_URL={boat-bay-url}.
The URL must be configured in some way for the specs to be uploaded by boat-bay, if not then the spec will only be linted.
The input spec should be the path of the spec or directory containing the specs you wish to upload.
The output is the location the lint reports get written to.
The
sourceKeyrefers to the source the spec/s should be uploaded to.
The other option is to send the upload request through a http request file like below:
###
POST http://localhost:8080/api/boat/boat-maven-plugin/repo-petstore/upload
Content-Type: application/json
{
"specs": [
{
"key": "renditionservice-client-api",
"name": "renditionservice-client-api-v1.2.0.yaml",
"openApi": "openapi: 3.0.3\r\ninfo:\r\n title: Rendition Client API\r\n version: 1.2.0\r\nservers:\r\n - url: 'http:\/\/localhost:4010'\r\n description: Prism mock server\r\ntags:\r\n - name: rendition service\r\npaths:\r\n '\/content\/{renditionId}':\r\n summary: Content stream by rendition ID or stream id\r\n description: 'Gets content stream of a document rendition by the rendition ID, or by it''s stream id, in case id begins with \"sid\"'\r\n get:\r\n tags:\r\n - client-api\r\n summary: 'Gets the content stream of the specified rendition, no rendition properties.'\r\n description: 'Gets the content stream of the specified rendition, no rendition properties.'\r\n operationId: renderContent\r\n parameters:\r\n - $ref: '#\/components\/parameters\/renditionId'\r\n responses:\r\n '200':\r\n description: Content stream data.\r\n content:\r\n '*\/*':\r\n schema:\r\n type: string\r\n format: binary\r\n '400':\r\n description: Could not read content stream.\r\n '404':\r\n description: The rendition is not found.\r\ncomponents:\r\n parameters:\r\n renditionId:\r\n name: renditionId\r\n in: path\r\n description: renditionId\r\n required: true\r\n schema:\r\n type: string\r\n",
"filename": "renditionservice-client-api-v1.2.0.yaml"
}
],
"location": "/Users/sophiej/Documents/Projects/opensauce/boat-bay/boat-bay-data",
"projectId": "com.backbase.oss.boat.renditionservice",
"artifactId": "renditionservice-spec",
"version": "1.2.0"
}The projectId and artifactId should be that of the project where the specs are coming from.
Boat Bay is a software tool that allows you to create portals for viewing Api Quality and Backwards Compatibility. It lints specs using a centralized repository of rules. These rules can be configured per portal, making it easy for teams to customize linting for their purposes. It also creates reports on the quality, highlighting sections of the spec that contain violations or could be improved, and a diff report showing the changes between your api versions, helping support backwards compatibility.
The base of this project is generated by JHipster.
Most of the custom code resides in boat-bay-server, to make it easier to distinguish between generated code and manually
written code this module's src directory has been split into two directories:
Boat Bay generates controller interfaces and models from the API specs in boat-bay-api. They are generated using the BOAT maven plugin.
###Implementing Boat Bay in Your Development Process
In the future, we plan to make Boat Bay accessible through BOAT as described in Uploading a spec this will be through an extended feature of the linting goal. This will allow a developer to upload a spec to Boat Bay through the build process. You can upload the same spec multiple times, while uploading from a project with a snapshot version the spec will be updated, otherwise a new spec will be created.
This application was generated using JHipster 6.10.5.
Before you can build this project, you must install and configure the following dependencies on your machine:
- Node.js: We use Node to run a development web server and build the project. Depending on your system, you can install Node either from source or as a pre-packaged bundle.
After installing Node, you should be able to run the following command to install development tools. You will only need to run this command when dependencies change in package.json.
npm install
We use npm scripts and Webpack as our build system.
Run the following commands in two separate terminals to create a blissful development experience where your browser auto-refreshes when files change on your hard drive.
./mvnw
npm start
Npm is also used to manage CSS and JavaScript dependencies used in this application. You can upgrade dependencies by
specifying a newer version in package.json. You can also run npm update and npm install to manage dependencies.
Add the help flag on any command to see how you can use it. For example, npm help update.
The npm run command will list all of the scripts available to run for this project.
JHipster ships with PWA (Progressive Web App) support, and it's turned off by default. One of the main components of a PWA is a service worker.
The service worker initialization code is commented out by default. To enable it, uncomment the following code in src/main/webapp/index.html:
<script>
if ('serviceWorker' in navigator) {
navigator.serviceWorker.register('./service-worker.js').then(function () {
console.log('Service Worker Registered');
});
}
</script>Note: Workbox powers JHipster's service worker. It dynamically generates the service-worker.js file.
For example, to add Leaflet library as a runtime dependency of your application, you would run following command:
npm install --save --save-exact leaflet
To benefit from TypeScript type definitions from DefinitelyTyped repository in development, you would run following command:
npm install --save-dev --save-exact @types/leaflet
Then you would import the JS and CSS files specified in library's installation instructions so that Webpack knows about them: Edit src/main/webapp/app/vendor.ts file:
import 'leaflet/dist/leaflet.js';
Edit src/main/webapp/content/scss/vendor.scss file:
@import '~leaflet/dist/leaflet.css';
Note: There are still a few other things remaining to do for Leaflet that we won't detail here.
For further instructions on how to develop with JHipster, have a look at Using JHipster in development.
You can also use Angular CLI to generate some custom client code.
For example, the following command:
ng generate component my-component
will generate few files:
create src/main/webapp/app/my-component/my-component.component.html
create src/main/webapp/app/my-component/my-component.component.ts
update src/main/webapp/app/app.module.ts
To build the final jar and optimize the Boat Bay application for production, run:
./mvnw -Pprod clean verify
This will concatenate and minify the client CSS and JavaScript files. It will also modify index.html so it references these new files.
To ensure everything worked, run:
java -jar target/*.jar
Then navigate to http://localhost:8080 in your browser.
Refer to Using JHipster in production for more details.
To package your application as a war in order to deploy it to an application server, run:
./mvnw -Pprod,war clean verify
To launch your application's tests, run:
./mvnw verify
Unit tests are run by Jest and written with Jasmine. They're located in src/test/javascript/ and can be run with:
npm test
For more information, refer to the Running tests page.
Sonar is used to analyse code quality. You can start a local Sonar server (accessible on http://localhost:9001) with:
docker-compose -f src/main/docker/sonar.yml up -d
You can run a Sonar analysis with using the sonar-scanner or by using the maven plugin.
Then, run a Sonar analysis:
./mvnw -Pprod clean verify sonar:sonar
If you need to re-run the Sonar phase, please be sure to specify at least the initialize phase since Sonar properties are loaded from the sonar-project.properties file.
./mvnw initialize sonar:sonar
For more information, refer to the Code quality page.
You can use Docker to improve your JHipster development experience. A number of docker-compose configuration are available in the src/main/docker folder to launch required third party services.
For example, to start a mysql database in a docker container, run:
docker-compose -f src/main/docker/mysql.yml up -d
To stop it and remove the container, run:
docker-compose -f src/main/docker/mysql.yml down
You can also fully dockerize your application and all the services that it depends on. To achieve this, first build a docker image of your app by running:
./mvnw -Pprod verify jib:dockerBuild
Then run:
docker-compose -f src/main/docker/app.yml up -d
For more information refer to Using Docker and Docker-Compose, this page also contains information on the docker-compose sub-generator (jhipster docker-compose), which is able to generate docker configurations for one or several JHipster applications.
To configure CI for your project, run the ci-cd sub-generator (jhipster ci-cd), this will let you generate configuration files for a number of Continuous Integration systems. Consult the Setting up Continuous Integration page for more information.