223 lines
9.8 KiB
Markdown
223 lines
9.8 KiB
Markdown
# REST version of Spring PetClinic Sample Application (spring-framework-petclinic extend )
|
|
|
|
[](https://github.com/spring-petclinic/spring-petclinic-rest/actions/workflows/maven-build.yml)
|
|
[](https://github.com/spring-petclinic/spring-petclinic-rest/actions/workflows/docker-build.yml)
|
|
|
|
This backend version of the Spring Petclinic application only provides a REST API. **There is no UI**.
|
|
The [spring-petclinic-angular project](https://github.com/spring-petclinic/spring-petclinic-angular) is a Angular front-end application which consumes the REST API.
|
|
|
|
## Understanding the Spring Petclinic application with a few diagrams
|
|
|
|
[See the presentation of the Spring Petclinic Framework version](http://fr.slideshare.net/AntoineRey/spring-framework-petclinic-sample-application)
|
|
|
|
### Petclinic ER Model
|
|
|
|
|
|
|
|
## Running Petclinic locally
|
|
|
|
### With Maven command line
|
|
```sh
|
|
git clone https://github.com/spring-petclinic/spring-petclinic-rest.git
|
|
cd spring-petclinic-rest
|
|
./mvnw spring-boot:run
|
|
```
|
|
|
|
### With Docker
|
|
```sh
|
|
docker run -p 9966:9966 springcommunity/spring-petclinic-rest
|
|
```
|
|
|
|
You can then access petclinic here: [http://localhost:9966/petclinic/](http://localhost:9966/petclinic/)
|
|
|
|
There is an actuator health check route as well:
|
|
* [http://localhost:9966/petclinic/actuator/health](http://localhost:9966/petclinic/actuator/health)
|
|
|
|
## OpenAPI REST API documentation
|
|
|
|
You can reach the Swagger UI with this URL (after application start):
|
|
[http://localhost:9966/petclinic/](http://localhost:9966/petclinic/swagger-ui.html).
|
|
|
|
You then can get the Open API description reaching this URL: [localhost:9966/petclinic/v3/api-docs](localhost:9966/petclinic/v3/api-docs).
|
|
|
|
## Screenshot of the Angular client
|
|
|
|
See its repository here: https://github.com/spring-petclinic/spring-petclinic-angular
|
|
|
|
<img width="1427" alt="spring-petclinic-angular2" src="https://cloud.githubusercontent.com/assets/838318/23263243/f4509c4a-f9dd-11e6-951b-69d0ef72d8bd.png">
|
|
|
|
## In case you find a bug/suggested improvement for Spring Petclinic
|
|
Our issue tracker is available here: https://github.com/spring-petclinic/spring-petclinic-rest/issues
|
|
|
|
|
|
## Database configuration
|
|
|
|
In its default configuration, Petclinic uses an in-memory database (HSQLDB) which gets populated at startup with data.
|
|
|
|
A similar setup is provided for MySQL and PostgreSQL if a persistent database configuration is needed.
|
|
|
|
Note that whenever the database type changes, the app needs to run with a different profile: `spring.profiles.active=mysql` for MySQL or `spring.profiles.active=postgres` for PostgreSQL.
|
|
See the [Spring Boot documentation](https://docs.spring.io/spring-boot/how-to/properties-and-configuration.html#howto.properties-and-configuration.set-active-spring-profiles) for more detail on how to set the active profile.
|
|
You can also change profile defined in the `application.properties` file.
|
|
For MySQL database, it is needed to change param `hsqldb` to `mysql` in the following line of `application.properies` file:
|
|
```properties
|
|
spring.profiles.active=hsqldb,spring-data-jpa
|
|
```
|
|
|
|
You can start MySQL or PostgreSQL locally with whatever installer works for your OS or use docker:
|
|
|
|
```bash
|
|
docker run -e MYSQL_USER=petclinic -e MYSQL_PASSWORD=petclinic -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=petclinic -p 3306:3306 mysql:8.4
|
|
```
|
|
|
|
or
|
|
|
|
```bash
|
|
docker run -e POSTGRES_USER=petclinic -e POSTGRES_PASSWORD=petclinic -e POSTGRES_DB=petclinic -p 5432:5432 postgres:16.3
|
|
```
|
|
|
|
Further documentation is provided for [MySQL](https://github.com/spring-projects/spring-petclinic/blob/main/src/main/resources/db/mysql/petclinic_db_setup_mysql.txt)
|
|
and [PostgreSQL](https://github.com/spring-projects/spring-petclinic/blob/main/src/main/resources/db/postgres/petclinic_db_setup_postgres.txt).
|
|
|
|
Instead of vanilla `docker` you can also use the provided `docker-compose.yml` file to start the database containers. Each one has a profile just like the Spring profile:
|
|
|
|
```bash
|
|
docker-compose --profile mysql up
|
|
```
|
|
|
|
or
|
|
|
|
```bash
|
|
docker-compose --profile postgres up
|
|
```
|
|
|
|
|
|
## API First Approach
|
|
|
|
This API is built following some [API First approach principles](https://swagger.io/resources/articles/adopting-an-api-first-approach/).
|
|
|
|
It is specified through the [OpenAPI](https://oai.github.io/Documentation/).
|
|
It is specified in this [file](./src/main/resources/openapi.yml).
|
|
|
|
Some of the required classes are generated during the build time.
|
|
Here are the generated file types:
|
|
* DTOs
|
|
* API template interfaces specifying methods to override in the controllers
|
|
|
|
To see how to get them generated you can read the next chapter.
|
|
|
|
## Generated code
|
|
|
|
Some of the required classes are generated during the build time using maven or any IDE (e.g., IntelliJ Idea or Eclipse).
|
|
|
|
All of these classes are generated into the ``target/generated-sources`` folder.
|
|
|
|
Here is a list of the generated packages and the corresponding tooling:
|
|
|
|
| Package name | Tool |
|
|
|------------------------------------------------|------------------|
|
|
| org.springframework.samples.petclinic.mapper | [MapStruct](https://mapstruct.org/) |
|
|
| org.springframework.samples.petclinic.rest.dto | [OpenAPI Generator maven plugin](https://github.com/OpenAPITools/openapi-generator/) |
|
|
|
|
|
|
To get both, you have to run the following command:
|
|
|
|
```jshelllanguage
|
|
mvn clean install
|
|
```
|
|
|
|
## Security configuration
|
|
In its default configuration, Petclinic doesn't have authentication and authorization enabled.
|
|
|
|
### Basic Authentication
|
|
In order to use the basic authentication functionality, turn in on from the `application.properties` file
|
|
```properties
|
|
petclinic.security.enable=true
|
|
```
|
|
This will secure all APIs and in order to access them, basic authentication is required.
|
|
Apart from authentication, APIs also require authorization. This is done via roles that a user can have.
|
|
The existing roles are listed below with the corresponding permissions
|
|
|
|
* `OWNER_ADMIN` -> `OwnerController`, `PetController`, `PetTypeController` (`getAllPetTypes` and `getPetType`), `VisitController`
|
|
* `VET_ADMIN` -> `PetTypeController`, `SpecialityController`, `VetController`
|
|
* `ADMIN` -> `UserController`
|
|
|
|
There is an existing user with the username `admin` and password `admin` that has access to all APIs.
|
|
In order to add a new user, please make `POST /api/users` request with the following payload:
|
|
|
|
```json
|
|
{
|
|
"username": "secondAdmin",
|
|
"password": "password",
|
|
"enabled": true,
|
|
"roles": [
|
|
{ "name" : "OWNER_ADMIN" }
|
|
]
|
|
}
|
|
```
|
|
|
|
## Working with Petclinic in Eclipse/STS
|
|
|
|
### prerequisites
|
|
The following items should be installed in your system:
|
|
* Maven 3 (https://maven.apache.org/install.html)
|
|
* git command line tool (https://help.github.com/articles/set-up-git)
|
|
* Eclipse with the m2e plugin (m2e is installed by default when using the STS (http://www.springsource.org/sts) distribution of Eclipse)
|
|
|
|
Note: when m2e is available, there is an m2 icon in Help -> About dialog.
|
|
If m2e is not there, just follow the install process here: http://eclipse.org/m2e/download/
|
|
* Eclipse with the [mapstruct plugin](https://mapstruct.org/documentation/ide-support/) installed.
|
|
|
|
### Steps:
|
|
|
|
1) In the command line
|
|
```sh
|
|
git clone https://github.com/spring-petclinic/spring-petclinic-rest.git
|
|
```
|
|
2) Inside Eclipse
|
|
```
|
|
File -> Import -> Maven -> Existing Maven project
|
|
```
|
|
|
|
|
|
## Looking for something in particular?
|
|
|
|
| Layer | Source |
|
|
|--|--|
|
|
| REST API controllers | [REST folder](src/main/java/org/springframework/samples/petclinic/rest) |
|
|
| Service | [ClinicServiceImpl.java](src/main/java/org/springframework/samples/petclinic/service/ClinicServiceImpl.java) |
|
|
| JDBC | [jdbc folder](src/main/java/org/springframework/samples/petclinic/repository/jdbc) |
|
|
| JPA | [jpa folder](src/main/java/org/springframework/samples/petclinic/repository/jpa) |
|
|
| Spring Data JPA | [springdatajpa folder](src/main/java/org/springframework/samples/petclinic/repository/springdatajpa) |
|
|
| Tests | [AbstractClinicServiceTests.java](src/test/java/org/springframework/samples/petclinic/service/clinicService/AbstractClinicServiceTests.java) |
|
|
|
|
|
|
## Publishing a Docker image
|
|
|
|
This application uses [Google Jib]([https://github.com/GoogleContainerTools/jib) to build an optimized Docker image into the [Docker Hub](https://cloud.docker.com/u/springcommunity/repository/docker/springcommunity/spring-petclinic-rest/) repository.
|
|
The [pom.xml](pom.xml) has been configured to publish the image with a the `springcommunity/spring-petclinic-rest`image name.
|
|
|
|
Command line to run:
|
|
```sh
|
|
mvn compile jib:build -X -DjibSerialize=true -Djib.to.auth.username=xxx -Djib.to.auth.password=xxxxx
|
|
```
|
|
|
|
## Interesting Spring Petclinic forks
|
|
|
|
The Spring Petclinic master branch in the main [spring-projects](https://github.com/spring-projects/spring-petclinic)
|
|
GitHub org is the "canonical" implementation, currently based on Spring Boot and Thymeleaf.
|
|
|
|
This [spring-petclinic-rest](https://github.com/spring-petclinic/spring-petclinic-rest/) project is one of the [several forks](https://spring-petclinic.github.io/docs/forks.html)
|
|
hosted in a special GitHub org: [spring-petclinic](https://github.com/spring-petclinic).
|
|
If you have a special interest in a different technology stack
|
|
that could be used to implement the Pet Clinic then please join the community there.
|
|
|
|
|
|
# Contributing
|
|
|
|
The [issue tracker](https://github.com/spring-petclinic/spring-petclinic-rest/issues) is the preferred channel for bug reports, features requests and submitting pull requests.
|
|
|
|
For pull requests, editor preferences are available in the [editor config](https://github.com/spring-petclinic/spring-petclinic-rest/blob/master/.editorconfig) for easy use in common text editors. Read more and download plugins at <http://editorconfig.org>.
|
|
|
|
|
|
|