This file provides general guidance for anyone contributing to IBM Cloud Java SDK projects produced by the IBM OpenAPI SDK Generator.
- Questions
- Coding Style
- Commit Messages
- Pull Requests
- Adding a new service
- Writing Tests
- Running Tests
- Code Coverage
- Generating Javadocs
- Publishing build artifacts
- Developer's Certificate of Origin 1.1
- Additional Resources
If you are having problems using the SDK or have a question about IBM Cloud services, please ask a question at Stack Overflow.
This SDK follows a coding style based on the Google Java coding style, with the following modifications:
- Max line length is 120 chars
- Only basic JavadocStyle is enforced
- Import ordering is not enforced
- VariableDeclarationUsageDistance is not enforced
- OverloadMethodsDeclarationOrder is not enforced
Commit messages should follow the Angular Commit Message Guidelines. This is because our release tool - semantic-release - uses this format for determining release versions and generating changelogs. Tools such as commitizen or commitlint can be used to help contributors and enforce commit messages. Here are some examples of acceptable commit messages, along with the release type that would be done based on the commit message:
| Commit message | Release type |
|---|---|
fix(resource controller): fix integration test to use correct credentials |
Patch Release |
feat(global catalog): add global-catalog service to project |
|
feat(global search): re-gen service code with new v3 API definitionBREAKING CHANGE: The global-search service has been updated to reflect version 3 of the API. |
If you want to contribute to the repository, here's a quick guide:
- Fork the repository.
- Develop and test your code changes:
- Follow the coding style as documented above
- To build/test:
mvn test - Please add one or more tests to validate your changes.
- Make sure everything builds/tests cleanly.
- The build will run the code style checker and flag any issues.
- Commit your changes
- Push to your fork and submit a pull request to the main branch.
- Be sure to sign the CLA.
This section will guide you through the steps to generate the Java code for a service and add the generated code to your SDK project.
- Validate the API definition - before trying to process the API definition with the SDK generator, we strongly recommend that you validate the API definition with the IBM OpenAPI Validator . Example:
lint-openapi -s example-service.yaml
This command will display a list of errors and warnings found in the API definition as well as a summary at the end. It's not required that you fix all errors and warnings before trying to use the SDK generator, but this step should identify any critical errors that will need to be fixed prior to the generation step.
- Recommended: Modify your API definition to configure the
apiPackageproperty. The value of this property should be the base package name associated with your SDK project (e.g.com.ibm.cloud.platform_services). All the generated service and model classes for the project will be contained in packages whose names start with this base package name. Here's an example:
info:
x-codegen-config:
java:
apiPackage: 'com.ibm.cloud.platform_services'By adding this configuration property to your API definition, you can avoid using the --api-package
command line option when running the SDK generator.
More details about SDK generator configuration properties can be found here.
- Next, run the SDK generator to process your API definition and generate the service and unit test code for the service.
You'll find instructions on how to install and run the SDK generator on the generator repository wiki.
Set the output location for the generated files to be the ./modules directory of the project.
If you did not configure the apiPackage configuration property in your API definition file(s), then
be sure to use the --api-package <base-package-name> command line option when running the generator to
ensure that source files are generated correctly.
Here is an example of how to generate the Java code for an API definition.
Suppose your API definition file is named my-service.json and contains the definition of the "My Service"
service.
To generate the code into your project, run these commands:
cd <project-root>
openapi-sdkgen.sh generate -g ibm-java -i my-service.json -o ./modules --api-package <base-package-name>
The generated service and unit test code will be written to a module directory
underneath ./modules.
The name of the module directory will reflect the service name.
For the example above, the module directory would be named my-service.
You will have one module directory underneath ./modules for each service contained in your
project (plus the common and coverage-reports modules).
Hint: you can generate an initial integration test for your service by including the --genITs option
when running the SDK generator. This will generate an integration test along with the service and
unit test code within the module directory for the service.
It is expected that the generated integration test is a starting point which will need manual editing
to form an effective integration test for the service.
- Copy the
service-pom.xmlfile tomodules/<module-name>/pom.xml, where<module-name>is the name of the new module directory. Edit this file and make these changes:
- Replace
MODULE-ARTIFACTIDwith the new module's artifactId (e.g. my-service) - Replace
MODULE-DESCRIPTIONwith a suitable description for the module (e.g. "My Service").
-
Update the service table in the
README.mdfile to add an entry for the new service. -
Next, modify the parent
pom.xmlfile to add an entry for the new service to the<modules>element. -
Next, modify the
coverage-reportsmodule's pom.xml to add a dependency entry for the new module so that its test coverage information will be accounted for in the aggregated coverage reports. -
Next, if you will be adding a generated "examples" class for the new service, then modify the
examplesmodule's pom.xml to add a dependency entry for the new module. -
Repeat the steps in this section for each service to be included in your project.
The Java integration tests use the TestNG testing framework.
With TestNG, you write methods containing your test code and annotate these methods with @Test.
You can create methods for setup and teardown of test infrastructure and annotate these
with a variety of @Before or @After annotations.
See the TestNG Docs for full details.
By default, when you run mvn verify (or mvn package), both unit and integration tests are run.
To run only the unit tests, run mvn test -DskipITs=true
To run the tests in a specific test class, use the -Dtest flag when invoking mvn test,
for example:
mvn test -Dtest=SdkCommonTest
To run a specific test, add the name of the test method, for example:
mvn test -Dtest=SdkCommonTest#testGetSdkHeaders
This repo uses Jacoco to measure code coverage. To obtain a code coverage report, run mvn clean verify
from the root of the project, and then view the coverage report in the modules/coverage-reports/target directory:
open modules/coverage-reports/target/site/jacoco-aggregate/index.html
To obtain a coverage report of only integration tests, run mvn clean verify -Dskip.unit.tests.
To generate the Javadocs for the project, run mvn site and then view the docs in the target/site/apidocs directory:
open target/site/apidocs/index.html
It is recommended that each Java SDK project publish its build artifacts (jars, pom.xml files, etc.) on the Maven Central repository, which is the default public repository for java artifacts.
For details on how to accomplish this within your Java SDK project's build, look here.
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.