diff --git a/CICD.txt b/CICD.txt deleted file mode 100644 index b870a128..00000000 --- a/CICD.txt +++ /dev/null @@ -1,20 +0,0 @@ -CI/CD Plan - -Validations -- Run codegen unit tests -- Run codegen integration tests -- Run usage unit tests -- Run spotless check -- Run PMD check - -PRs -- Build the codegen artifact -- Perform Validations - -Main Build -- Build the codegen artifact -- Perform Validations -- Build docker image, with pom version. -- Push docker image - -DO GITHUB ACTIONS CONTAIN INPUTS FOR RELEASE VERSIONING LIKE GITLAB? \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index 8cd8a644..b2a8f92f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,7 +2,8 @@ FROM amazoncorretto:24-alpine LABEL maintainer="radiantlogic" -COPY ./codegen-modules/openapi-java-client-codegen/target/openapi-java-client-codegen-*.jar /openapi-java-client-codegen.jar +# The GitHub action will result in the jar at the root of the project by this point +COPY ./*.jar /app.jar RUN mkdir /input RUN mkdir /output diff --git a/README.md b/README.md index 7daf7888..94620297 100644 --- a/README.md +++ b/README.md @@ -27,63 +27,10 @@ The primary use for the generated code is to support building custom connectors TBD -## Development +## Additional Documentation -### Modules +- [Detailed Explanation of "Raw" Types In Generated Code](./docs/RAW_TYPES.md) +- [Development Guide](./docs/DEVELOPMENT.md) +- [GitHub Actions CI/CD](./docs/CICD.md) -This is a multi-module maven project. The primary modules for the codegen will be found in the `codegen-modules` directory. Modules that exist to use (and therefore test) the generated code will be found in the `usage-modules` directory. - -By default, only the `codegen-modules` will be impacted by maven commands. Running commands with the `usage` profile (ie, `mvn -P codegen ...`) will execute commands on the `usage-modules` and running commands with the `all` profile (ie, `mvn -P all ...`) will execute commands on all modules. - -### Requirements - -- Java 24 -- Maven 3.9.9 - -### Version Managers - -This project fully supports `sdkman` for selecting the correct dependency versions. - -## Running Locally - -### IntelliJ Pre-Requisite - -Whether running the full codegen application or individual unit tests, the default IntelliJ settings will not correctly execute the program. The following adjustments will need to be made. - -1. The working directory should be set to `./codegen-modules/openapi-java-client-codegen`. -2. The maven `generate-resources` goal must be run before launch. IntelliJ by default does not run the whole maven lifecycle so this must be manually configured. This can be configured from any IntelliJ run configuration with the following steps: - 1. Open the run configuration. - 2. Select `Modify Options` -> `Before Launch Task`. - 3. Add a new task for `Add Maven Goal`. - 4. When configuring the goal, the `Command Line Options` value should be set to `generate-resources`. - 5. Apply the changes. - -### Full Codegen From the CLI - -This executes the codegen CLI tool from source using the following command: - -```bash -mvn clean compile \ - -pl codegen-modules/openapi-java-client-codegen -am \ - exec:exec@generate \ - -DprogramArgs="ARGUMENTS GO HERE" -``` - -To see all possible arguments, run with `-DprogramArgs='-h'` - -### Full Codegen From IntelliJ - -Run the main class `com.radiantlogic.openapi.codegen.javaclient.Runner` in the module `codegen-modules/openapi-java-client-codegen`. Make sure to configure the pre-requisite settings described above. - -### End-to-End Testing - -A robust set of end-to-end tests have been constructed to validate the behavior of the Java client code generation. This is how to use them. - -First is the `integration.com.radiantlogic.openapi.codegen.javaclient.CodegenIT` class in `codegen-modules/openapi-java-client-codegen`. This test suite executes the code generation against a wide range of official OpenAPI specs from a variety of companies. It generates, compiles, and installs the maven artifacts from those specs. - -Next is the full test suite in `usage-modules/openapi-java-client-usage`. Once all tests from `CodegenIT` complete successfully, all the artifacts will be available in the local `.m2` directory. At that point the test suite in this project can be run to execute a variety of java client operations against a mock server. This validates that the generated code performs as-expected. - -## CI/CD - -TBD -Don't forget about the username & password variables in docs \ No newline at end of file +NOTE: Pay special attention to the CI/CD guide for release instructions. \ No newline at end of file diff --git a/docs/CICD.md b/docs/CICD.md new file mode 100644 index 00000000..02b48e9d --- /dev/null +++ b/docs/CICD.md @@ -0,0 +1,23 @@ +# GitHub Action CI/CD + +## Workflows + +### Main + +This workflow runs automatically whenever a push is made to the `main` branch. It builds the maven artifact, runs all validations, and then builds and pushes the docker image. The maven artifact and docker image tag will use the version in the pom.xml (ie, `1.0.0-SNAPSHOT`). + +### PR + +This workflow runs automatically when a PR is opened, and then re-runs every time a push is made to that PR. It builds the maven artifact and runs all validations. + +### Release + +This workflow is manually triggered from the Actions screen in GitHub. It builds the maven artifact, runs all validations, and then builds and pushes the docker image. It also performs a series of important release-related tasks. + +To manually trigger it, a semver-compliant version number (ie, `1.0.0`) must be supplied via an input. Any semver-compliant version number can be used. See the screenshot below for details. + +![Running Release](./cicd/run_release.png) + +The pipeline will set that version number as the project version, abd the maven artifact and docker image tag will use that version. After the image is published, the repository will have a git tag applied with that version number (ie, `v1.0.0`) and the pom.xml will automatically be bumped to the next highest patch version snapshot (ie, `1.0.1-SNAPSHOT`). + +It is strongly recommended that all releases are done using this workflow to guarantee consistency. \ No newline at end of file diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 00000000..ce20c375 --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,55 @@ +# Development Guide + +### Modules + +This is a multi-module maven project. The primary modules for the codegen will be found in the `codegen-modules` directory. Modules that exist to use (and therefore test) the generated code will be found in the `usage-modules` directory. + +By default, only the `codegen-modules` will be impacted by maven commands. Running commands with the `usage` profile (ie, `mvn -P codegen ...`) will execute commands on the `usage-modules` and running commands with the `all` profile (ie, `mvn -P all ...`) will execute commands on all modules. + +### Requirements + +- Java 24 +- Maven 3.9.9 + +### Version Managers + +This project fully supports `sdkman` for selecting the correct dependency versions. + +## Running Locally + +### IntelliJ Pre-Requisite + +Whether running the full codegen application or individual unit tests, the default IntelliJ settings will not correctly execute the program. The following adjustments will need to be made. + +1. The working directory should be set to `./codegen-modules/openapi-java-client-codegen`. +2. The maven `generate-resources` goal must be run before launch. IntelliJ by default does not run the whole maven lifecycle so this must be manually configured. This can be configured from any IntelliJ run configuration with the following steps: + 1. Open the run configuration. + 2. Select `Modify Options` -> `Before Launch Task`. + 3. Add a new task for `Add Maven Goal`. + 4. When configuring the goal, the `Command Line Options` value should be set to `generate-resources`. + 5. Apply the changes. + +### Full Codegen From the CLI + +This executes the codegen CLI tool from source using the following command: + +```bash +mvn clean compile \ + -pl codegen-modules/openapi-java-client-codegen -am \ + exec:exec@generate \ + -DprogramArgs="ARGUMENTS GO HERE" +``` + +To see all possible arguments, run with `-DprogramArgs='-h'` + +### Full Codegen From IntelliJ + +Run the main class `com.radiantlogic.openapi.codegen.javaclient.Runner` in the module `codegen-modules/openapi-java-client-codegen`. Make sure to configure the pre-requisite settings described above. + +### End-to-End Testing + +A robust set of end-to-end tests have been constructed to validate the behavior of the Java client code generation. This is how to use them. + +First is the `integration.com.radiantlogic.openapi.codegen.javaclient.CodegenIT` class in `codegen-modules/openapi-java-client-codegen`. This test suite executes the code generation against a wide range of official OpenAPI specs from a variety of companies. It generates, compiles, and installs the maven artifacts from those specs. + +Next is the full test suite in `usage-modules/openapi-java-client-usage`. Once all tests from `CodegenIT` complete successfully, all the artifacts will be available in the local `.m2` directory. At that point the test suite in this project can be run to execute a variety of java client operations against a mock server. This validates that the generated code performs as-expected. \ No newline at end of file diff --git a/docs/cicd/run_release.png b/docs/cicd/run_release.png new file mode 100644 index 00000000..d8ff499a Binary files /dev/null and b/docs/cicd/run_release.png differ