Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Alliedium/springboot-api-rest-example
Spring Boot API RESTful with tests, swagger e JWT 🚀
https://github.com/Alliedium/springboot-api-rest-example
Last synced: 3 months ago
JSON representation
Spring Boot API RESTful with tests, swagger e JWT 🚀
- Host: GitHub
- URL: https://github.com/Alliedium/springboot-api-rest-example
- Owner: Alliedium
- License: gpl-3.0
- Fork: true (Throyer/springboot-api-rest-example)
- Created: 2022-09-19T19:30:17.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2023-06-21T10:36:14.000Z (about 1 year ago)
- Last Synced: 2024-01-21T06:43:04.500Z (5 months ago)
- Language: Java
- Homepage: https://throyer-crud-api.herokuapp.com
- Size: 1.91 MB
- Stars: 2
- Watchers: 0
- Forks: 10
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists
- awesome-jenkins - project
README
>[🇧🇷 In Portuguese](https://github.com/Throyer/springboot-api-crud/blob/master/assets/readme.md#spring-boot-api-crud)
>
> [🐬 MySQL/MariaDB (outdated) implementation](https://github.com/Throyer/springboot-api-crud/tree/mariadb#readme)
Spring Boot API RESTful
A complete user registry, with access permissions, JWT token, integration and unit tests, using the RESTful API pattern.
[**Live demo on heroku**](https://throyer-crud-api.herokuapp.com)
## Table of Contents
- [Features](#features)
- [Requirements](#requirements)
- [Entities](#entities)
- [Installation](#installation)
- [Running a specific test](#tests)
- [Swagger](#swagger)
- [Database Migrations](#database-migrations)
- [Docker](#docker-examples)
- [Environment variables](#environment-variables)
# Features
## Requirements
- Postgres: `^13`
- Java: `^17`
- Maven: `^3.8.4`
This project was started with [Spring Initializr](https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.6.2&packaging=jar&jvmVersion=17&groupId=com.github.throyer.common&artifactId=api&name=api&description=CRUD%20API&packageName=com.github.throyer.common.api&dependencies=devtools,lombok,web,security,thymeleaf,mysql,h2,data-jpa,flyway,jooq).
## Entities
>[🚨 draw.io file here](./assets/database/diagram.drawio)
## Installation
```shell
# clone the repository and access the directory.
$ git clone [email protected]:Throyer/springboot-api-crud.git && cd springboot-api-crud
# download dependencies
$ mvn install -DskipTests
# run the application
$ mvn spring-boot:run
# run the tests
$ mvn test
# to build for production
$ mvn clean package
# to generate the coverage report after testing (available at: target/site/jacoco/index.html)
$ mvn jacoco:report
```
## Tests
[](https://coveralls.io/repos/github/Throyer/springboot-api-crud/badge.svg?branch=master)
## Running a specific test
use the parameter `-Dtest=#`
for example the integration test. creating a user:
```
$ mvn test -Dtest=UsersControllerIntegrationTests#should_save_a_new_user
```
## Swagger
Once the application is up, it is available at: [localhost:8080/documentation](localhost:8080/documentation)
[example on heroku](https://throyer-crud-api.herokuapp.com/documentation)
---
## Database Migrations
Creating database migration files
> 🚨 make sure you have maven in your environment and that you are in the correct directory __./api__
>
> if you using docker-compose
> ```
> .docker/scripts/mvn migration:generate -Dname=my-migration-name
> ```
- Java based migrations
```bash
mvn migration:generate -Dname=my-migration-name
```
- SQL based migrations
```bash
mvn migration:generate -Dname=my-migration-name -Dsql
```
---
## Docker examples
> 🚨 create `environment` file and add permission to execute scripts
>
> ```shell
> cp .docker/.env.example .docker/.env && chmod -R +x .docker/scripts
> ```
- docker-compose for development
- starting containers
```
.docker/scripts/develop up -d
```
- removing contaiers
```
.docker/scripts/develop down
```
- show backend logs
```
.docker/scripts/develop logs -f api
```
- docker-compose for production
```
.docker/scripts/production up -d --build
```
```
.docker/scripts/production down
```
## Environment variables
| **Description** | **Parameter** | **Default values** |
|------------------------------------------|------------------------------------|---------------------------|
| server port | `SERVER_PORT` | 8080 |
| database url | `DB_URL` | localhost:5432/common_app |
| username (database) | `DB_USERNAME` | root |
| user password (database) | `DB_PASSWORD` | root |
| displays the generated sql in the logger | `DB_SHOW_SQL` | false |
| set maximum database connections | `DB_MAX_CONNECTIONS` | 5 |
| secret value in token generation | `TOKEN_SECRET` | secret |
| token expiration time in hours | `TOKEN_EXPIRATION_IN_HOURS` | 24 |
| refresh token expiry time in days | `REFRESH_TOKEN_EXPIRATION_IN_DAYS` | 7 |
| SMTP server address | `SMTP_HOST` | smtp.gmail.com |
| SMTP server port | `SMTP_PORT` | 587 |
| SMTP username | `SMTP_USERNAME` | user |
| SMTP server password | `SMTP_PASSWORD` | secret |
| time for recovery email to expire | `MINUTES_TO_EXPIRE_RECOVERY_CODE` | 20 |
| max requests per minute | `MAX_REQUESTS_PER_MINUTE` | 10 |
| swagger username | `SWAGGER_USERNAME` | `null` |
| swagger password | `SWAGGER_PASSWORD` | `null` |
> these variables are defined in: [**application.properties**](./src/main/resources/application.properties)
>
> ```shell
> # to change the value of some environment variable at runtime
> # on execution, just pass it as a parameter. (like --SERVER_PORT=80).
> $ java -jar api-4.1.2.jar --SERVER_PORT=80
> ```
> [All options of `aplication.properties` here](https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html).
>
> [All **features** of Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html).