Skip to content

Commit b7ddde6

Browse files
ThroyerThroyer
committed
Update readme
1 parent 0f081d9 commit b7ddde6

File tree

2 files changed

+205
-63
lines changed

2 files changed

+205
-63
lines changed

‎README.md

Lines changed: 53 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1+
[In Portuguese](assests/readme.md)
2+
13
<p align="center">
24
<a href="https://github.com/Throyer" target="blank"><img src="./assets/tecnologias.png" width="560" alt="Tecnologias" /></a>
35
</p>
46

57
<h1 align="center">Spring Boot API CRUD</h1>
68
<p align="center">
7-
Um cadastro de usuários completo, com permissões de acesso, token JWT testes de integração e unitários, no padrão API RESTful.
9+
A complete user registry, with access permissions, JWT token, integration and unit tests, using the RESTful API pattern.
810
</p>
911

1012
<br>
@@ -16,15 +18,14 @@
1618
<a href="https://throyer-crud-api.herokuapp.com" target="blank"><img src="./assets/demo.gif" alt="Demonstration" /></a>
1719
</p>
1820

19-
## Sumario
21+
## Table of Contents
2022

2123
- [Features](#features)
22-
- [Requisitos](#requisitos)
23-
- [Entidades](#entidades)
24-
- [Instalação](#instalação)
25-
- [Rodando um teste especifico](#rodando-um-teste-especifico)
26-
- [Documentação do Swagger](#documentação-do-swagger)
27-
- [Postman](#postman)
24+
- [Prerequisites](#prerequisites)
25+
- [Entities](#entities)
26+
- [Installation](#installation)
27+
- [Running a specific test](#running-a-specific-test)
28+
- [Swagger](#swagger)
2829
- [Database Migrations](#database-migrations)
2930
- [Variaveis de ambiente](#variáveis-de-ambiente)
3031

@@ -36,76 +37,65 @@
3637

3738

3839

39-
## Requisitos
40+
## Prerequisites
4041

4142
- MariaDB: `^10.6.1`
4243
- Java: `^17`
43-
> recomendo a instalação do maven localmente, mas o projeto tem uma versão portatil nos arquivos [`mvnw`](./mvnw) e [`mvnw.cmd`](./mvnw.cmd)
44+
- Maven: `^3.8.4`
4445

45-
Esse projeto foi configurado com [Spring Initializr](https://start.spring.io/).
46+
This project was started with [Spring Initializr](https://start.spring.io/).
4647

47-
## Entidades
48+
## Entities
4849

4950
<p>
5051
<img src="./database_diagram/spring_boot_crud_database_diagram.png" alt="database diagram" />
5152
</p>
5253

5354
> arquivo do [draw.io](./der/spring_boot_crud_database_diagram.drawio)
5455
55-
## Instalação
56-
57-
> Caso tiver o maven instalado localmente substitua `mvnw` por `mvn` (_para usuários do zsh adicione o comando `bash` antes de mvnw_)
58-
56+
## Installation
5957

6058
```shell
61-
# Clone o repositório e acesse o diretório.
59+
# clone the repository and access the directory.
6260
$ git clone [email protected]:Throyer/springboot-api-crud.git && cd springboot-api-crud
6361

64-
# Baixe as dependencias (o parametro -DskipTests pula os testes)
65-
$ mvnw install -DskipTests
62+
# download dependencies
63+
$ mvn install -DskipTests
6664

67-
# Rode a aplicação
68-
$ mvnw spring-boot:run
65+
# run the application
66+
$ mvn spring-boot:run
6967

70-
# Para rodar os testes
71-
$ mvnw test
68+
# run the tests
69+
$ mvn test
7270

73-
# Para buildar para produção
74-
$ mvnw clean package
71+
# to build for production
72+
$ mvn clean package
7573

76-
# Para gerar o relatório de cobertura apos os testes (fica disponível em: target/site/jacoco/index.html)
77-
$ mvnw jacoco:report
74+
# to generate the coverage report after testing (available at: target/site/jacoco/index.html)
75+
$ mvn jacoco:report
7876
```
7977

8078

81-
## Rodando um teste especifico
82-
use o parâmetro `-Dtest=<Classe>#<metodo>`
79+
## Running a specific test
80+
use the parameter `-Dtest=<class>#<method>`
8381

8482

85-
por exemplo o teste de integração de criação usuário:
83+
for example the integration test. creating a user:
8684
```
87-
$ mvnw test -Dtest=UsuariosControllerIntegrationTests#should_save_a_new_user
85+
$ mvnw test -Dtest=UsersControllerIntegrationTests#should_save_a_new_user
8886
```
8987

9088

91-
## Documentação do Swagger
92-
Assim que a aplicação estiver de pé, fica disponível em: [localhost:8080/documentation](localhost:8080/documentation)
93-
89+
## Swagger
90+
Once the application is up, it is available at: [localhost:8080/documentation](localhost:8080/documentation)
9491

95-
[exemplo no heroku](https://throyer-crud-api.herokuapp.com/documentation)
9692

97-
## Postman
98-
>Clique [**aqui**](./postman/crud_api.postman_collection.json) para acessar o aquivo `json` da coleção do postman.
99-
>
100-
>> _🚨 this file is deprecated!_
101-
102-
<br>
103-
<br>
93+
[example on heroku](https://throyer-crud-api.herokuapp.com/documentation)
10494

10595
---
10696

10797
## Database Migrations
108-
Criando arquivos de arquivos de migração
98+
Creating database migration files
10999

110100
- Java based migrations
111101
```bash
@@ -119,32 +109,32 @@ Criando arquivos de arquivos de migração
119109

120110
---
121111

122-
## Variáveis de ambiente
112+
## Environment variables
123113

124114
| **Descrição** | **parâmetro** | **Valor padrão** |
125115
| ------------------------------------------- | -------------------------------------- | ------------------------- |
126-
| porta da aplicação | `SERVER_PORT` | 8080 |
127-
| url do banco | `DB_URL` | localhost:3306/common_app |
128-
| nome de usuário (banco) | `DB_USERNAME` | root |
129-
| senha do usuário (banco) | `DB_PASSWORD` | root |
130-
| mostrar sql na saida | `DB_SHOW_SQL` | false |
131-
| máximo de conexões com o banco | `DB_MAX_CONNECTIONS` | 5 |
132-
| valor do secret na geração dos tokens | `TOKEN_SECRET` | secret |
133-
| tempo de expiração do token em horas | `TOKEN_EXPIRATION_IN_HOURS` | 24 |
134-
| tempo de expiração do refresh token em dias | `REFRESH_TOKEN_EXPIRATION_IN_DAYS` | 7 |
135-
| endereço do servidor smtp | `SMTP_HOST` | smtp.gmail.com |
136-
| porta do servidor smtp | `SMTP_PORT` | 587 |
137-
| nome de usuário smtp | `SMTP_USERNAME` | user |
138-
| senha do servidor smtp | `SMTP_PASSWORD` | secret |
139-
140-
> são definidas em: [**application.properties**](./src/main/resources/application.properties)
116+
| Server port | `SERVER_PORT` | 8080 |
117+
| database url | `DB_URL` | localhost:3306/common_app |
118+
| username (database) | `DB_USERNAME` | root |
119+
| user password (database) | `DB_PASSWORD` | root |
120+
| displays the generated sql in the logger | `DB_SHOW_SQL` | false |
121+
| set maximum database connections | `DB_MAX_CONNECTIONS` | 5 |
122+
| secret value in token generation | `TOKEN_SECRET` | secret |
123+
| token expiration time in hours | `TOKEN_EXPIRATION_IN_HOURS` | 24 |
124+
| refresh token expiry time in days | `REFRESH_TOKEN_EXPIRATION_IN_DAYS` | 7 |
125+
| SMTP server address | `SMTP_HOST` | smtp.gmail.com |
126+
| SMTP server port | `SMTP_PORT` | 587 |
127+
| SMTP username | `SMTP_USERNAME` | user |
128+
| SMTP server password | `SMTP_PASSWORD` | secret |
129+
130+
> these variables are defined in: [**application.properties**](./src/main/resources/application.properties)
141131
>
142132
> ```shell
143-
> # para mudar o valor de alguma variável de ambiente
144-
> # na execução basta passar ela como parâmetro. (como --SERVER_PORT=80 por exemplo).
133+
> # to change the value of some environment variable at runtime
134+
> # on execution, just pass it as a parameter. (like --SERVER_PORT=80).
145135
> $ java -jar api-3.0.3.RELEASE.jar --SERVER_PORT=80
146136
> ```
147137
>
148-
> > [Todas opções do `aplication.properties` **padrões** no Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html).
138+
> > [All options of `aplication.properties` here](https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html).
149139
> >
150-
> > [Todas **funcionalidades** do Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html).
140+
> > [All **features** of Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html).

‎assets/readme.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
[Em Inglês](../README.md)
2+
3+
<p align="center">
4+
<a href="https://github.com/Throyer" target="blank"><img src="./tecnologias.png" width="560" alt="Tecnologias" /></a>
5+
</p>
6+
7+
<h1 align="center">Spring Boot API CRUD</h1>
8+
<p align="center">
9+
Um cadastro de usuários completo, com permissões de acesso, token JWT testes de integração e unitários, no padrão API RESTful.
10+
</p>
11+
12+
<br>
13+
<br>
14+
15+
[**Live demo on heroku**](https://throyer-crud-api.herokuapp.com)
16+
17+
<p align="center">
18+
<a href="https://throyer-crud-api.herokuapp.com" target="blank"><img src="./demo.gif" alt="Demonstration" /></a>
19+
</p>
20+
21+
## Sumario
22+
23+
- [Features](#features)
24+
- [Requisitos](#requisitos)
25+
- [Entidades](#entidades)
26+
- [Instalação](#instalação)
27+
- [Rodando um teste especifico](#rodando-um-teste-especifico)
28+
- [Documentação do Swagger](#documentação-do-swagger)
29+
- [Postman](#postman)
30+
- [Database Migrations](#database-migrations)
31+
- [Variaveis de ambiente](#variáveis-de-ambiente)
32+
33+
# Features
34+
35+
<p align="center">
36+
<a href="https://throyer-crud-api.herokuapp.com" target="blank"><img src="https://i.imgur.com/YWjBtvG.png" alt="Tecnologias" /></a>
37+
</p>
38+
39+
40+
41+
## Requisitos
42+
43+
- MariaDB: `^10.6.1`
44+
- Java: `^17`
45+
> recomendo a instalação do maven localmente, mas o projeto tem uma versão portatil nos arquivos [`mvnw`](./mvnw) e [`mvnw.cmd`](./mvnw.cmd)
46+
47+
Esse projeto foi configurado com [Spring Initializr](https://start.spring.io/).
48+
49+
## Entidades
50+
51+
<p>
52+
<img src="../database_diagram/spring_boot_crud_database_diagram.png" alt="database diagram" />
53+
</p>
54+
55+
> arquivo do [draw.io](./der/spring_boot_crud_database_diagram.drawio)
56+
57+
## Instalação
58+
59+
> Caso tiver o maven instalado localmente substitua `mvnw` por `mvn` (_para usuários do zsh adicione o comando `bash` antes de mvnw_)
60+
61+
62+
```shell
63+
# Clone o repositório e acesse o diretório.
64+
$ git clone [email protected]:Throyer/springboot-api-crud.git && cd springboot-api-crud
65+
66+
# Baixe as dependencias (o parametro -DskipTests pula os testes)
67+
$ mvnw install -DskipTests
68+
69+
# Rode a aplicação
70+
$ mvnw spring-boot:run
71+
72+
# Para rodar os testes
73+
$ mvnw test
74+
75+
# Para buildar para produção
76+
$ mvnw clean package
77+
78+
# Para gerar o relatório de cobertura apos os testes (fica disponível em: target/site/jacoco/index.html)
79+
$ mvnw jacoco:report
80+
```
81+
82+
83+
## Rodando um teste especifico
84+
use o parâmetro `-Dtest=<Classe>#<metodo>`
85+
86+
87+
por exemplo o teste de integração de criação usuário:
88+
```
89+
$ mvnw test -Dtest=UsuariosControllerIntegrationTests#should_save_a_new_user
90+
```
91+
92+
93+
## Documentação do Swagger
94+
Assim que a aplicação estiver de pé, fica disponível em: [localhost:8080/documentation](localhost:8080/documentation)
95+
96+
97+
[exemplo no heroku](https://throyer-crud-api.herokuapp.com/documentation)
98+
99+
## Postman
100+
>Clique [**aqui**](./postman/crud_api.postman_collection.json) para acessar o aquivo `json` da coleção do postman.
101+
>
102+
>> _🚨 this file is deprecated!_
103+
104+
<br>
105+
<br>
106+
107+
---
108+
109+
## Database Migrations
110+
Criando arquivos de arquivos de migração
111+
112+
- Java based migrations
113+
```bash
114+
mvn migration:generate -Dname=my-migration-name
115+
```
116+
117+
- SQL based migrations
118+
```bash
119+
mvn migration:generate -Dname=my-migration-name -Dsql
120+
```
121+
122+
---
123+
124+
## Variáveis de ambiente
125+
126+
| **Descrição** | **parâmetro** | **Valor padrão** |
127+
| ------------------------------------------- | -------------------------------------- | ------------------------- |
128+
| porta da aplicação | `SERVER_PORT` | 8080 |
129+
| url do banco | `DB_URL` | localhost:3306/common_app |
130+
| nome de usuário (banco) | `DB_USERNAME` | root |
131+
| senha do usuário (banco) | `DB_PASSWORD` | root |
132+
| mostrar sql na saida | `DB_SHOW_SQL` | false |
133+
| máximo de conexões com o banco | `DB_MAX_CONNECTIONS` | 5 |
134+
| valor do secret na geração dos tokens | `TOKEN_SECRET` | secret |
135+
| tempo de expiração do token em horas | `TOKEN_EXPIRATION_IN_HOURS` | 24 |
136+
| tempo de expiração do refresh token em dias | `REFRESH_TOKEN_EXPIRATION_IN_DAYS` | 7 |
137+
| endereço do servidor smtp | `SMTP_HOST` | smtp.gmail.com |
138+
| porta do servidor smtp | `SMTP_PORT` | 587 |
139+
| nome de usuário smtp | `SMTP_USERNAME` | user |
140+
| senha do servidor smtp | `SMTP_PASSWORD` | secret |
141+
142+
> são definidas em: [**application.properties**](./src/main/resources/application.properties)
143+
>
144+
> ```shell
145+
> # para mudar o valor de alguma variável de ambiente
146+
> # na execução basta passar ela como parâmetro. (como --SERVER_PORT=80 por exemplo).
147+
> $ java -jar api-3.0.3.RELEASE.jar --SERVER_PORT=80
148+
> ```
149+
>
150+
> > [Todas opções do `aplication.properties` **padrões** no Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html).
151+
> >
152+
> > [Todas **funcionalidades** do Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html).

0 commit comments

Comments
 (0)