This project uses a Spec-First approach, where we always start with our spec and use it generates base code, tests, documentation, etc.
More on the Spec Driven Approach can be found at the confluence link below: https://sherwoodforest.atlassian.net/wiki/spaces/ARC/pages/2754609318/Spec+Driven+Development
The boilerplate is comprsed of a spec, src, hooks, and build folder, along with supporting files and directories. The developer will only have to make edits in the spec and src folders.
spec: Has the main OpenAPI spec and all the pieces that make up the spec.
src: Has the developer's code
hooks: Stores all the git hooks. These git hooks are only active until you run a build that pushes these hooks into the .git directory
build: Has the auto-generated code with the endpoints and models.
- This folder will only appear after running a project build.
Before we get started we will set up our Git Hooks and review Bakkt's Git Strategies.
Build the project by running ./gradlew build, this will run the gradle task installLocalGitHook.
- Add Project Details to the Gradle Properties File
- Write Service Spec
- Rename Package of SRC Folder
- Generate Controllers and Models from the API Spec
- Write Business Logic by Extending Generated Code
- Start the App
- Write and Run Test Cases
- Create and Publish Docker Image of App
- Configure CI Pipeline
- Configure CD Pipeline
Go to the gradle.properties file in the root directory and edit the values to reflect your microservice.
The spec is broken into different pieces found in the ./spec folder, and the main spec is named openapi-v1.0. Change the version of this spec name everytime you update the version of the service.
Go to the ./spec folder and follow the Readme.md for details on the best way to write your spec.
Review the documentation found below for further details: https://sherwoodforest.atlassian.net/wiki/spaces/ARC/pages/2754806111/Writing+OpenAPI+Spec
Go the ./src and rename the package directory to match the package name defined in the gradle.properties file.
For instance, the package name defined in the gradle.properties file in this template is com.platform.boilerplate.example so the folder name in the ./src folder should be named the same thing (com.platform.boilerplate.example)
The command below will build the generated controller and model code using the spec.
./gradlew buildThe build command takes the spec file (located in the ./spec folder) and uses it to generate code and documentation for your controller and model. The code can be found in the ./build/generated/src folder and documentation can be found in the ./build/generated/docs folder.
Add your customizations and business logic in the package directory in the ./src folder.
Extend the classes generated by the code generator in the build folder, below is an example:
@Controller
public class PetController extends AbstractPetsController{
@Override
public Mono<Pet> showPetById(String petId) {
return Mono.justOrEmpty(new Pet(Long.parseLong(petId), "Bob"));
}
}
- Add the Controller annotation on the top
- Use the methods that do not end with api.
- The model classes are created in the generated code and is referenced in this code.
- If you need a model that isn't associated with an endpoint then manually code it in the src folder.
./gradlew runThe added endpoints should be visible in the Swagger and Redocly pages.
http://localhost:9080/swagger.html
http://localhost:9080/redocly.html
Reference best practices found at the page: https://sherwoodforest.atlassian.net/wiki/spaces/ARC/pages/2744451265/Testing
Go to the ci-pipeline.yml file and add your project details.
The CD Pipeline files will be setup in the Pipelines repository (https://github.com/Sherwood-forest/pipelines).
Follow the documentation found at the following page for further details on the setup: https://sherwoodforest.atlassian.net/wiki/spaces/ARC/pages/2766701107/CD+Pipeline+Setup