feat: update documentation for new feature

EPE - Spring Boot Resftul microservice Template Testing the Semantic Release !!!!!!!!!!!!!!!!!!!

Template starter repository for creating spring boot restful microservices.

Description

This repository provides a template for building Spring Boot Restful Microservices. It is designed to streamline the development process by offering pre-configured setup with commonly used libraries and best practices specific to "Enterprise Platform Engineering" team. The template includes essential features like REST API Standards, Observability configurations, Logging patterns, Security and more.

Features

• Spring Boot: A production-ready framework for building Java-based microservices.
• REST API: Pre-configured controllers and endpoints to easily expose RESTFul services automatically created based on openapi specification and maven plugin.
• Exception Handling: Centralized Exception handling.
• Logging: Spring default logging, with pre-configured code to log server requests and responses, and also client request and responses.
• Testing: Pre-configured unit and integration tests with Junit and Mockito.
• Postman: Integration with neumann to run postman collection at scheduled intervals.
• Docker Support: Dockerfile configuration for containerization.
• Kubernetes Support: Kubernetes manifest files for container orchestration.
• local deployment: Pre-configured script to run application within a local kubernetes cluster hosted on Docker Desktop.
• API Documentation: Swagger UI integration from API documentation and testing.

Getting Started

Prerequisites

• Java 17 or higher
• Maven 3.8+
• Docker ( optional - if intend to run locally)

Project Structure

• src/main/java: Main Source code including service, repositories and models. Controllers are automatically generated from maven openapi-generator-plugin.
• src/main/resources: Configuration file including -
  • application.yml containing application settings.
  • /spec containing openapi specifications.
• src/test/java: junit test cases.
• pom.xml: Project dependencies and build configuration.
• Dockerfile: Instructions for building a Docker Image of the service.
• kubernetes/*: folder containing manifest files for creating kubernetes resources.
• postman/*: Folder containing postman collection and environment configuration.
  • index.html: html file for displaying postman execution report.
• .github/workflows: github action files for building and deploying application.
• localhost-runner.bat: bat file containing instructions to deploy application onto local kubernetes cluster.

Configurations

1. Application Properties
   • Configure application setting in src/main/resources/application.yml
   • Configure environment specific properties in kubernetes/{environment}/kubernetes-configmap.yml
   • Update kubernetes/deployment.yaml vault configuration
     • Update project specific CLIENT_ID and CLIENT_SECRET ( Replace with keys defined within vault ) Refer documentation for configuring vault.

Generate a new repository from the template

1. Create a new repository by clicking on the "Use this template"
2. Provide Repository details
3. Update pom.xml
   • update groupId, artifactId, name and description.
4. Deploy to Sandbox
   • Run Build JAR / Publish Docker / Deploy-Sandbox action to validate deployment of application to sandbox AKS cluster.
5. Run a postman test
   • Enable GitHub Page
     • Go to Settings and set the below configuration
   • Execute Postman run with Reports action
   • On Successful execution test results would be uploaded to github pages whose link can be found in the About section

Project Specific configuration

1. Update/Delete Files with details specific to the microservice
   • README.md
   • README2.md
   • localhost-runner.bat
   • screenshots/*
   • postman/*
     • delete the template collection and add project specific postman scripts
     • update package.json with the correct collection and environment names

       "sandbox-tests": "newman run postman/collections/{YOUR COLLECTION NAME} -e postman/environments/sandbox_postman_environment.json --insecure -r cli,htmlextra --reporter-htmlextra-export ./newman/sandbox-tests.html",
       "dev-tests": "newman run postman/collections/{YOUR COLLECTION NAME}  -e postman/environments/dev_postman_environment.json --insecure -r cli,htmlextra --reporter-htmlextra-export ./newman/dev-tests.html",
       "qa-tests": "newman run postman/collections/{YOUR COLLECTION NAME}  -e postman/environments/qa_postman_environment.json --insecure -r cli,htmlextra --reporter-htmlextra-export ./newman/qa-tests.html"
       

   • pom.xml -
     • Update openapi-generator-maven-plugin configuration with correct open-api specifications
   • CODEOWNERS
     • Update with userId of the code owner.

2.Add Project to SonarCloud

• Raise a request to add the newly created project to sonarcloud dashboard.
  • Request using this link
  • Select Delivery Automation Service Request
  • 
• Update sonarcloud-scan.yml
  • include project name

       run:  mvn -B verify sonar:sonar -Dsonar.projectKey=sherwin-williams-co_{YOUR REPO NAME} -Dsonar.organization=sherwin-williams-co -Dsonar.host.url=https://sonarcloud.io -Dsonar.login=$SONARCLOUD_TOKEN

Running the Application

1. Maven Commands
   • Build application using maven commands mvn clean install
   • Run using spring maven plugin mvn spring-boot:run
2. Docker Commands
   • Build an docker image docker build -t {image-name}:{tag} .
   • Run and start a docker container docker run -p {host-port}:{container-port} {image-name}
3. Localhost Runner Script
   • Run the bat script from command prompt ./localhost-runner.bat
     • Pre-requisite - Docker Desktop installed and running on local machine.

Testing

• Run unit tests mvn test

API Documentation

• Access the API Documentation at http://localhost:8080/swagger-ui.html once application is running.