- Project Information
- Running example
- Applications Demo
- Technology Stack
- Requirements
- Installation Information
- Rest app configure
- Web app configure
- Run local tests
- Run mutation testing
- Run load testing
- Run application with PostgreSQL
- Run with docker-compose
- Local tests with Postman
- Documenting a REST API
- OpenAPI generated server
- Swagger generated client
- Excel Import and Export
- Generate test data
- Create and restore database archive
🎙️ 'Setlist Organizer' is a web application for organizing repertoires of musical bands. 🎙️
Applications deployed on Heroku
The web application will be accessible at:
https://setlist-organizer-web.herokuapp.com/
The rest application will be accessible at:
https://setlist-organizer-rest.herokuapp.com/
API documentation with Swagger UI:
https://setlist-organizer-rest.herokuapp.com/swagger-ui/index.html
- Programming Language: Java
- Core Framework: Spring boot
- Data Access:
- Validation Framework: Hibernate Validator
- Annotation processor:
- Build System: Maven
- Control System: Git
- License: Apache license, version 2.0
- Code Style: Codacy
- Automated Testing:
- Mutation Testing: PIT
- Load Testing: Gatling
- Log:
- Monitoring:
- Database:
- Database migration tool: Flyway
- JSON library:
- Generate test data: Java Faker
- Java API for Microsoft Excel: Apache POI
- API documentation generation:
- Code generation:
- Template Engine: Thymeleaf
- CSS Framework: Bootstrap
- App containerization: Docker
The following software is required for the complete workflow (from git clone to the running Docker Container). The specified versions are the tested ones.
- JDK 11+
- Git 2.25.1+
- Apache Maven 3.6.3+
- Docker 20.10.12+
- Docker-compose 1.29.2+
- Scala-sdk 2.13.6+ (for load testing)
$ git clone https://github.com/Brest-Java-Course-2021-2/Maksim-Meliashchuk-Setlist-Organizer.git
$ cd Maksim-Meliashchuk-Setlist-Organizer
$ mvn clean install
Setup rest-app in application.properties:
Profile | Description |
---|---|
dev | Run application with embedded H2 database in memory |
postgres | Run application with PostgreSQL database |
test | Run application with embedded H2 database in memory, Flyway migration disabled |
jdbc | Interact with a database by using Spring JDBC |
jpa | Interact with a database by using Spring Data JPA |
Example:
spring.profiles.active=dev, jpa
The web application has three web client implementations for making HTTP calls to REST application services - RestTemplate, a new WebClient alternative and automatically generated by the Swagger Codegen client API - ApiClient. Setup web-app in application.properties.
Using RestTemplate (is deprecated since Spring 5):
app.httpClient = RestTemplate
Using WebClient (exists since Spring 5):
app.httpClient = WebClient
Using ApiClient (OkHttpClient and GSON based):
app.httpClient = ApiClient
ApiClient is a preferable choice.
Embedded H2 in memory.
In the root directory of the project:
$ java -jar -Dspring.profiles.active=dev,jpa rest-app/target/rest-app-1.0-SNAPSHOT.jar
To start the OpenAPI generated server:
$ java -jar -Dspring.profiles.active=dev,jpa rest-app-openapi/target/rest-app-openapi-1.0-SNAPSHOT.jar
The rest application will be accessible at http://localhost:8088.
$ java -jar web-app/target/web-app-1.0-SNAPSHOT.jar
The web application will be accessible at http://localhost:8080.
PIT runs unit tests against automatically modified versions of the application code, the most effective way to use mutation testing is to run it frequently against only the code that has been changed. TargetClasses and TargetTests to limit the tests available to be run added to parent project POM:
<configuration>
<targetClasses>
<param>com.epam.brest.service.impl.jpa.*</param>
</targetClasses>
<targetTests>
<param>com.epam.brest.service.impl.jpa.*</param>
</targetTests>
</configuration>
Run directly from the commandline:
$ mvn test-compile org.pitest:pitest-maven:mutationCoverage
PIT Test Coverage Report will be accessible: /service/target/pit-reports/index.html
Testing starts with 10 users per second making two requests to the repertoire, holding at that concurrency for five seconds. Then RestSimulationLocal test scenario increases the number of users per second by 5, 5 times, holding for 5 seconds each time. Every request must return an HTTP 200 status code to pass the test. Run the test in the root directory of the project:
$ sh gatling-test.sh
Make sure the rest-app at http://localhost:8088 is running. Gatling reports generated in: /gatling-test/target/gatling/
PostgreSQL require(can be customized in application-postgres.properties file in prod-db module):
driver
- org.postgresql.Driverurl
- jdbc:postgresql://localhost:5432/setlistOrganizeruser
- postgrespassword
- password
Run rest-app with PostgreSQL:
$ java -jar -Dspring.profiles.active=postgres,jpa rest-app/target/rest-app-1.0-SNAPSHOT.jar
In the root directory of the project, run the rest-app with monitoring and web-app in one go:
$ sudo docker-compose up --build
The web application will be accessible at http://localhost:8080
The rest application will be accessible at http://localhost:8088
The PostgreSQL database can be accessed in docker at: http://localhost:5432
Micrometer by default shows jvm metrics at http://localhost:8088/actuator/prometheus
Access the Prometheus webUI on http://localhost:9090
Access the Grafana webUI with jvm-micrometer dashboard on http://localhost:3000
To stop the containers:
$ sudo docker-compose down
To test the REST API, you can use the Postman collection to access the API endpoints:
See the Postman online documentation.
Using OpenAPI 3.0
The OpenAPI descriptions in JSON format will be available at the path: http://localhost:8088/v3/api-docs
The OpenAPI descriptions in YAML format will be available at the path: http://localhost:8088/v3/api-docs.yaml
API documentation with Swagger UI: http://localhost:8088/swagger-ui/index.html
Automatically generated by the OpenAPI Generator project by using the OpenAPI-Spec and the openapi-generator-maven-plugin.
An OpenAPI document that conforms to the OpenAPI Specification openapi.yaml has been generated automatically by using springdoc-openapi-maven-plugin in the module rest-app.
Refer to the module rest-app-openapi for more information.
Automatically generated by the Swagger Codegen by using the swagger-codegen-maven-plugin.
An OpenAPI document that conforms to the OpenAPI Specification openapi.yaml has been generated automatically by using springdoc-openapi-maven-plugin in the module rest-app.
Refer to the module service-swagger-client for more information.
These REST applications have several endpoints (/export/excel
and /import/excel
) to create and import Excel files using
Apache POI.
Please, after running the REST application, refer to the API documentation with Swagger UI for more information.
Following are samples of Excel files that can be imported:
These REST applications have several endpoints /fill
to generate fake data for showcase with uses Java Faker.
It is possible specify language for generated data (EN, DE, FR), default EN.
It is possible specify count fakes data, use parameter to multiply default size (default value 1).
Please, after running the REST application, refer to the API documentation with Swagger UI for more information.
The database archive can be created and exported in XML format and saved as a ZIP archive.
These REST applications have a /downloadZipFile
endpoint with the ability to create a database archive and a /uploadZipFile
endpoint
with the ability to restore the database from the archive.
The Simple API for XML (SAX) is used to parse XML documents.
The following is an example of a ZIP file that is the result of an export that can be imported: