Skip to content

Home

Jump to bottom
Billy Bolton edited this page Apr 19, 2024 · 21 revisions

Overview

This project is an opinionated framework that extends Spring Boot to empower developers to implement APIs with CRUD and/or search support with ease.

When using these libraries for your own components (Controller, Service, Mapper, Repository), you can also use the testing libraries we ship to further reduce the amount of code you need to write.

Motivation

Many Spring Boot RESTful APIs contain the same design patterns across microservices, their respective domains. These libraries are meant to reduce boilerplate code that are necessary to support CRUD and search operations. This project also has plans to

A similar approach is taken for the integration tests included in this project. Many developers write tests ad-hoc for the business logic that they require, however, when looking at the design patterns at high level, this logic can also be abstracted. Therefore, we are also shipping an integration testing framework to easily provide coverage for the libraries contained in this project.

This project also provides support to automatically generate code for Spring Boot components using only entity models, thereby reducing the amount of code a developer needs to write even further.

Getting Started

Local Environment Setup

This project strives to ensure all dependencies use the most current up-to-date LTS versions.

Name Version Documentation Instructions
Docker Desktop 4.25.2 (129061) https://docs.docker.com This project uses Liquibase to track the database changelogs used in the examples submodules, while populating test data for automated and manual testing. As such, please ensure Docker is running in the background by opening Docker Desktop. You may notice Liquibase fails at start up, otherwise.
Java See here https://docs.oracle.com/en/java/javase/21/ Ensure Java with the specified version is sourced by configuring your preferred IDE and/or manually in your computer settings.

IDE Configuration

JetBrains IntelliJ

Configuring Annotation Processing

Please follow the documentation for Configuring an annotation profile in IntelliJ, ensuring that the Enable annotation processing setting is enabled.
Eclipse Please follow the documentation for Eclipse JDT-APT Project here.
VSCode Please follow the documentation for Annotation processing support in Gradle for VSCode.

Secrets

The root directory has a file called secrets-TEMPLATE.gradle that stores they key-value that Gradle will use to source private dependencies and running CI/CD processes like Sonar Cloud scanning.

Using Secrets Locally

To populate these secrets:

  1. Duplicate the secrets-TEMPLATE.gradle file and rename it to secrets.gradle. (The secrets.gradle file is included in .gitignore.)

  2. Replace all respective values. You may reference secret configuration for the respective services below.

Github

Complete the steps for "Creating a personal access token (classic)", ensuring that it has read packages permission selected.

Key Example Value Description
GPR_USER "Jane Doe" Github Username
GPR_KEY "ghp_xXxxxXXXxXxxxxXxXXXXxxxxXxXxXXXxXxXX" Github Access Token
Sonar

Forking this project will not fork other CI/CD processes that use third-party tools & services, like Sonar Cloud. Contributors are free to use whichever tooling they'd like in their forked repository. As such, explaining steps to replicate the GitHub Actions in this repository to work in your own forked repository is out-of-scope for this document. If you would like to use Sonar Cloud locally, however, please reference the Sonar Cloud setup documentation here and populate the secrets below in your secrets.gradle file.

Key Example Value Description
SONAR_ORGANIZATION "MyOrganization" Your GitHub organization or username.
SONAR_PROJECT_KEY "MyOrganization_springharvest" Your organization's Sonar Cloud project name.
SONAR_TOKEN "ghp_xXxxxXXXxXxxxxXxXXXXxxxxXxXxXXXxXxXX" Your secure Sonar Cloud token that is associated with your personal or organization configured Sonar project.

Contributors

After completing the steps above, contributors should continue their setup by review the Contributor Guide.

Users

After completing the steps above, users should continue their setup by following the proceeding instructions:

Ingest Libraries as Dependencies

Ingest the desired Spring Harvest libraries into your preferred build tool. The available libraries / dependencies can be found in this project's packages repository.

Maven

<dependency>
  <groupId>dev.springharvest</groupId>
  <artifactId>{library-name}</artifactId>
  <version>${version}</version>
</dependency>

Gradle

compileOnly "dev.springharvest:{library-name}:${version}"
implementation "dev.springharvest:{library-name}:${version}"
testImplementation "dev.springharvest:{library-name}:${version}"
annotationProcessor "dev.springharvest:{library-name}:${version}"
testAnnotationProcessor "dev.springharvest:{library-name}:${version}"
compileOnly files("$buildDir/generated/sources/annotationProcessor/java/main")
annotationProcessor files("$buildDir/generated/sources/annotationProcessor/java/main")

Examples

Users are provided examples that illustrate how to use the libraries in this project in their own.

Clean & Build

Ensure Docker is running in the background.

From the root directory of this repository, run the following CLI comment, where {APP} is replaced by the example you are attempting to run.

./gradlew :projects:examples:{APP} clean build -x test

BootRun

Ensure Docker is running in the background.

From the root directory of this repository, run the following CLI comment, where {APP} is replaced by the example you are attempting to run.

./gradlew :projects:examples:{APP} bootRun -Pspring.profiles.active=postgres,liquibase

Test

Ensure Docker is running in the background.

From the root directory of this repository, run the following CLI comment, where {APP} is replaced by the example you are attempting to run.

./gradlew :projects:examples:{APP} test

Clone this wiki locally