diff --git a/readme.md b/readme.md index a50d3b99e..e1e59d68d 100644 --- a/readme.md +++ b/readme.md @@ -14,35 +14,36 @@ The [spring-petclinic-angular project](https://github.com/spring-petclinic/sprin ![alt petclinic-ermodel](petclinic-ermodel.png) -## Running petclinic locally +## Running Petclinic locally -### With maven command line -``` +### 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 are actuator health check and info routes as well: +There is an actuator health check route as well: * [http://localhost:9966/petclinic/actuator/health](http://localhost:9966/petclinic/actuator/health) -* [http://localhost:9966/petclinic/actuator/info](http://localhost:9966/petclinic/actuator/info) -## OpenAPI REST API documentation presented here (after application start): +## OpenAPI REST API documentation -You can reach the swagger UI with this URL +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). +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 + spring-petclinic-angular2 ## In case you find a bug/suggested improvement for Spring Petclinic @@ -51,44 +52,40 @@ Our issue tracker is available here: https://github.com/spring-petclinic/spring- ## Database configuration -In its default configuration, Petclinic uses an in-memory database (HSQLDB) which -gets populated at startup with data. -A similar setups is provided for MySql and PostgreSQL in case a persistent database configuration is needed. -To run petclinic locally using persistent database, it is needed to change profile defined in application.properties file. +In its default configuration, Petclinic uses an in-memory database (HSQLDB) which gets populated at startup with data. +Similar setups are provided for MySql and PostgreSQL in case a persistent database configuration is needed. However, to populate them with sample data, you should follow additional instructions from either `src/main/resources/db/mysql/petclinic_db_setup_mysql.txt` (for MySQL) or `src/main/resources/db/postgresql/petclinic_db_setup_postgresql.txt` (for PostgreSQL) file. -For MySQL database, it is needed to change param "hsqldb" to "mysql" in string -``` +To run Petclinic locally using persistent database, it is also needed to change profile defined in `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 ``` - defined in application.properties file. - -Before do this, would be good to check properties defined in application-mysql.properties file. +Before doing this, it would be good to check properties defined in `application-mysql.properties` file: -``` +```properties spring.datasource.url = jdbc:mysql://localhost:3306/petclinic?useUnicode=true spring.datasource.username=pc -spring.datasource.password=petclinic -spring.datasource.driver-class-name=com.mysql.jdbc.Driver +spring.datasource.password=petclinic +spring.datasource.driver-class-name=com.mysql.jdbc.Driver spring.jpa.database=MYSQL spring.jpa.database-platform=org.hibernate.dialect.MySQLDialect spring.jpa.hibernate.ddl-auto=none -``` +``` -You may also start a MySql database with docker: +You may also start a MySql database with Docker: -``` +```sh docker run --name mysql-petclinic -e MYSQL_ROOT_PASSWORD=petclinic -e MYSQL_DATABASE=petclinic -p 3306:3306 mysql:5.7.8 ``` -For PostgeSQL database, it is needed to change param "hsqldb" to "postgresql" in string -``` +For PostgeSQL database, it is needed to change param `hsqldb` to `postgresql` in the following line of `application.properties` file: +```properties spring.profiles.active=hsqldb,spring-data-jpa ``` - defined in application.properties file. +Before doing this, it would be good to check properties defined in `application-postgresql.properties` file: -Before do this, would be good to check properties defined in application-postgresql.properties file. - -``` +```properties spring.datasource.url=jdbc:postgresql://localhost:5432/petclinic spring.datasource.username=postgres spring.datasource.password=petclinic @@ -97,9 +94,9 @@ spring.jpa.database=POSTGRESQL spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect spring.jpa.hibernate.ddl-auto=none ``` -You may also start a Postgres database with docker: +You may also start a Postgres database with Docker: -``` +```sh docker run --name postgres-petclinic -e POSTGRES_PASSWORD=petclinic -e POSTGRES_DB=petclinic -p 5432:5432 -d postgres:9.6.0 ``` ## API First Approach @@ -140,28 +137,29 @@ mvn clean install 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 -``` +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 + +* `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 use the following API: -``` -POST /api/users + 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" } - ] + ] } ``` @@ -180,7 +178,7 @@ If m2e is not there, just follow the install process here: http://eclipse.org/m2 ### Steps: 1) In the command line -``` +```sh git clone https://github.com/spring-petclinic/spring-petclinic-rest.git ``` 2) Inside Eclipse @@ -203,13 +201,11 @@ File -> Import -> Maven -> Existing Maven project ## 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. +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 ``` @@ -232,4 +228,3 @@ For pull requests, editor preferences are available in the [editor config](https -