luzzetti / spring-boot-angular-scaffolding

Spring Boot and Angular multi-module project that builds as a single jar.

spring-boot-angular-scaffolding

To learn how to set up a project like this one, check out the Integrate Angular with a Spring Boot project post.

This project is a multi-module application, using the following frameworks: Spring Boot for the backend and Angular for the frontend. The project can be built into a single jar file using Maven.

• Getting Started
  • Prerequisites
  • Running the project
• Profiles summary
  • Spring profiles
  • Maven profiles
• API documentation
  • Swagger
  • OpenAPI
• Client code generation
• Working with frontend on a local environment
• Running test suits
  • Backend
  • Frontend
• SonarQube analysis on a local environment
  • SonarQube Prerequisites
  • Full analysis
  • Backend analysis
  • Frontend analysis
  • Verifying results
• Forking this repository
• Built With

Getting Started

Prerequisites

Backend:

• JDK 13+
• Maven (or you can use mvnw provided in the project)
• Docker
• Docker Compose

Frontend:

• Node.js version that you specify in the frontend-maven-plugin configuration - Angular requires an active or maintenance LTS version of Node.js. For the reference, you can check out this unofficial compatibility matrix.

Running the project

First, clone this repository.

Then, build it locally with:

mvn clean install

You can run the project from command line with:

mvn spring-boot:run -Dspring-boot.run.profiles=dev

As a result, you should be able to visit the home page on http://localhost:8080/:

Profiles summary

The project can be built with various different profiles to allow for flexible configuration. Below you'll find a short summary of the available profiles.

Spring profiles

• dev - for local development. Allows things like handling requests from http://localhost:4200/.
• angular - special profile used for client code generation. Applied automatically when the angular Maven profile is enabled.

Maven profiles

• sonar-cloud - for code analysis on push to master
• code-coverage - for including code coverage reports from the backend module during a sonar analysis
• frontend-pre-sonar - for including code coverage reports from the frontend module during a sonar analysis
• frontend-sonar - for running only a sonar analysis for the frontend module
• angular - for generating client code

API documentation

The backend module serves one endpoint for testing purposes. First, build and run the application. Then you'll be able to reach the API docs.

Swagger

The Swagger UI page: http://localhost:8080/swagger-ui.html.

OpenAPI

• The OpenAPI description in the json format is available at the following url: http://localhost:8080/v3/api-docs.
• The API specification is also available in the yaml format under the http://localhost:8080/v3/api-docs.yaml link.

Client code generation

Compatibility

Right now openapi-generator supports Angular 11.0.0. Although the generated code works with Angular 12+ used in this project, it's strongly recommended to update the generator plugin as soon as it starts supporting Angular 12.0.0 (see Issue #9511).

Generating code

To run client code generation using the openapi-generator-maven-plugin execute the following command:

cd backend
mvn clean verify -Pangular -DskipTests

The application will be started so that the API specification can be obtained from the Open API endpoint. The generated code is available in the frontend/src/main/angular/src/backend directory. Don't edit those files manually.

Working with frontend on a local environment

If you want to see how changes you make in the frontend code affect the application you don't need to build it together with the backend module every time (mvn clean install). Use the following commands:

mvn spring-boot:run -Dspring-boot.run.profiles=dev

cd frontend/src/main/angular
ng serve

and visit http://localhost:4200/. The frontend application reloads automatically on code change.

Running test suits

Backend

Run unit tests with the following command in the project directory:

mvn test

Run all tests with the following command in the project directory:

mvn verify

Frontend

Run all tests for the Angular code with:

cd frontend/src/main/angular
ng test

SonarQube analysis on a local environment

SonarQube Prerequisites

• Read the Boost project quality with SonarQube – local code analysis post to set up dependencies properly.
• You'll need Chrome installed on your machine for running a frontend analysis with code coverage.
• Read the How to add an Angular module built with Maven to a SonarQube analysis to learn more about analysing a multi-module maven application.

Full analysis

You can run analysis for the whole project (both backend and frontend):

mvn clean verify sonar:sonar -Pfrontend-pre-sonar -Pcode-coverage -Dsonar.login=your_username -Dsonar.password=your_password

Backend analysis

You can run a separate analysis for the backend module:

cd backend
mvn clean verify sonar:sonar -Pcode-coverage -Dsonar.login=your_username -Dsonar.password=your_password

Frontend analysis

You can run a separate analysis for the frontend module:

cd frontend
mvn sonar:sonar -Pfrontend-pre-sonar -Dsonar.login=your_username -Dsonar.password=your_password

Or use the shell script which you can find in the closing paragraphs of the How to add an Angular module built with Maven to a SonarQube analysis post.

Verifying results

Visit the Projects page and choose the right project. Depending on which modules were analysed you should see one, two, or three projects.

Forking this repository

Update project metadata

• Make sure to provide your own values for <name>, <description>, <artifactId> and <groupId> in the pom.xml, backend/pom.xml and frontend/pom.xml files.

GitHub Actions and SonarCloud analysis

• Remove the .github/workflows/build.yml file if you don't want to configure GitHub Actions for your repository.
• If you don't want to configure SonarCloud for your repository: remove the sonar-cloud profile from pom.xml, <sonar.projectKey> and <sonar.projectName> from backend/pom.xml and all <sonar…> properties from frontend/pom.xml
• If you do want to configure GitHub Actions and SonarCloud analysis, add your own SONAR_TOKEN to your repository and customize all mentioned above<sonar…> properties in the pom.xml files.

Built With

• Maven
• Spring Boot v2.5+
• Angular v12+
• frontend-maven-plugin
• springdoc-openapi
• Bootstrap v5+
• ng-bootstrap

Table of contents generated with markdown-toc