7.1 Contribute to this project

Contribute to this project

I encourage you to contribute to this project based on your needs. If you miss a certain feature, or you want to improve an error message or whatever, feel free to follow the GitHub-Process as described here: https://guides.github.com/introduction/flow/

That basically means:

1. Fork the project to create your own copy on GitHub
2. Create a Feature- or Bugfix-Branch on your Fork
   • this allows you to create smaller Pull-Requests, which makes it easier to merge them into the main code
3. Create an issue related to your changes
   • if you add a certain feature, bugfix, etc. which is not yet tracked, please create an issue for it
   • this helps to reference these changes
4. Make changes, as you want in your branch
   • for major changes, please add appropriate integration tests
5. Build your Swagger-Promote package locally to test with as described here
6. If you believe it makes sense to include your changes in the main project, please create a Pull-Request based on your branch.
   • create a Pull-Request from your Branch into the Develop branch
   • with that, all integration tests are executed automatically to make sure, no breaking changes are introduced with your change
     • you may check this yourself as it shown in your Pull-Request
   • finally an Administrator will verify the changes, provide feedback or merge the changes into the main project

Compile your own Swagger-Promote release

After you have made a change, bugfix, etc. or you want to test a change I made to the project, it is a good idea to build your own Swagger-Promote release based on the develop branch or your own fork. In order to build a local package please execute the following steps:

1. Make sure you have Maven installed by calling mvn -v.
   • if not you may easily install it with Chocolatey
2. And you need a Git-Client:
   • Also a Git-Client can be installed with Chocolatey
3. Clone Swagger-Promote to your local system using Git:
   https://github.com/Axway-API-Management-Plus/apimanager-swagger-promote.git
   This clones the default develop branch containing all fixes and enhancements which will go into the next release
4. Then execute:
   mvn clean package -DskipTests=true
   Skipping tests might be a good idea, as they require an API-Manager up & running, which will be used to insert 50+ Test-APIs. Maybe something you don't want.
5. This creates a SNAPSHOT-Release of the development branch in modules/distribution/target/apimanager-swagger-promote-X.Y.Z-SNAPSHOT.tar.gz Extract it was the normal release and do your tests to validate proper behavior of Swagger-Promote.

You can do the same including all or just one test:

• If you want to build, but skip the tests call mvn clean package -DskipTests=true
• If you want to run a specific test, call mvn clean verify -Dit.test=<nameOfYourTest>

How the program works internally

Before adding major changes, please make sure you have read and understood the following chapter as it describes the internal principles of the program. Your changes must well integrate into this concept otherwise you a potential Pull-Request from you cannot be merged into the Main-Project.

The main concept is to compare the desired with the actual state of the API and only perform changes that are required.

Running tests

To create an reliable and sustainable project the project is using complete End-2-End integration-tests right from beginning. With these End-2-End-Tests the API-Developer Development-Process is simulated, by importing a Swagger+Contract into API-Manager, validating the exposed API, then maybe do some small changes, re-importing it again and validate the exposed API has been updated.

For testing I'm using the Citrus-Framework and tests are executed after each build on Travis CI, where an API-Manager container is started, handling all Imports, Updates, etc. These tests are currently performed by an API-Manager 7.6.2 SP1.

To verify compatibility with your API-Manager version, you can run all the integration tests locally. Just do the following very simple steps:

• install Maven and Git on your machine
• start an API-Manager instance (on a Container, VM, Remote, ...)
• clone this project using git clone https://github.com/Axway-API-Management-Plus/apimanager-swagger-promote.git
• in the cloned project open the file: citrus-global-variables.properties to configure:
  • the hostname of the API-Manager
  • if needed the username + password
• open a command line/shell
• run the test with "mvn clean verify"

Some of the tests part of the suite expect some policies to be configured. These tests will fail, if the following policies are not configured:

• Request policies: "Request policy 1"
• Response policies: "Response policy 1"
• Routing policies: "Routing policy 1", "Secure Headers"
• Fault Handler policies: "Default Fault Handler", "Faulthandler policy 1"
• Token information policies: "Tokeninfo policy 1"
• Inbound security policies: "Inbound security policy 1"

And to validate Custom-Properties are working please configure the following custom-properties for your API-Manager:

• customProperty1: As an Input-Field
• customProperty2: As a select option (values 1, 2, 3)
• customProperty3: As a toggle (values: true & false)

Please note: Custom-Properties are only supported by API-Manager 7.6.2 and higher, but as long as non configured in the API-Contract the program should work with version 7.5.3 as well.