From 29cc40c594af6e3d6b0e28c4ff251266e4451b9c Mon Sep 17 00:00:00 2001 From: Alexandre Touret Date: Wed, 16 Mar 2022 11:05:54 +0100 Subject: [PATCH 1/4] feat: add documentation for API First approach --- readme.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/readme.md b/readme.md index 8ee0d5401..65eed319c 100644 --- a/readme.md +++ b/readme.md @@ -101,6 +101,27 @@ You may also start a Postgres database with docker: ``` docker run --name postgres-petclinic -e POSTGRES_PASSWORD=petclinic -e POSTGRES_DB=petclinic -p 5432:5432 -d postgres:9.6.0 ``` +## 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 + +The whole configuration of the generation is handled by [OpenAPI Generator maven plugin](https://github.com/OpenAPITools/openapi-generator/) and is located in the [pom.xml](./pom.xml) file. + +To run this plugin and by this way generate the classes, you have to run the following command: + +```jshelllanguage +mvn clean install +``` + +You could then find all the generated source code in the ``target/generated-sources/openapi`` folder. ## Security configuration In its default configuration, Petclinic doesn't have authentication and authorization enabled. From 46a87e79e8084b3696e5d01405ecc8fb381bd20c Mon Sep 17 00:00:00 2001 From: Alexandre Touret Date: Wed, 16 Mar 2022 11:10:53 +0100 Subject: [PATCH 2/4] feat: add short mapstruct documentation --- readme.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 65eed319c..c5e5c7078 100644 --- a/readme.md +++ b/readme.md @@ -115,7 +115,10 @@ Here are the generated file types: The whole configuration of the generation is handled by [OpenAPI Generator maven plugin](https://github.com/OpenAPITools/openapi-generator/) and is located in the [pom.xml](./pom.xml) file. -To run this plugin and by this way generate the classes, you have to run the following command: +Besides of that, the mapping between the DTOs and entities are done using [MapStruct](https://mapstruct.org/). +The mapper generation is done automatically during the build time. + +To run both and by this way generate the classes, you have to run the following command: ```jshelllanguage mvn clean install From 7b668329efc4600e692bb2ab333c46a4bc458817 Mon Sep 17 00:00:00 2001 From: Alexandre Touret Date: Mon, 21 Mar 2022 17:29:29 +0100 Subject: [PATCH 3/4] feat: add documentation for mapstruct in Eclipse --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index c5e5c7078..092ec07e6 100644 --- a/readme.md +++ b/readme.md @@ -165,7 +165,7 @@ The following items should be installed in your system: 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: From db88514cb3615bc0727b050de6f16928e82b5af4 Mon Sep 17 00:00:00 2001 From: Alexandre Touret Date: Mon, 21 Mar 2022 17:39:43 +0100 Subject: [PATCH 4/4] feat: refactoring of the existing documentation --- readme.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/readme.md b/readme.md index 092ec07e6..9c60f337f 100644 --- a/readme.md +++ b/readme.md @@ -113,19 +113,28 @@ Here are the generated file types: * DTOs * API template interfaces specifying methods to override in the controllers -The whole configuration of the generation is handled by [OpenAPI Generator maven plugin](https://github.com/OpenAPITools/openapi-generator/) and is located in the [pom.xml](./pom.xml) file. +To see how to get them generated you can read the next chapter. -Besides of that, the mapping between the DTOs and entities are done using [MapStruct](https://mapstruct.org/). -The mapper generation is done automatically during the build time. +## Generated code -To run both and by this way generate the classes, you have to run the following command: +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 ``` -You could then find all the generated source code in the ``target/generated-sources/openapi`` folder. - ## Security configuration In its default configuration, Petclinic doesn't have authentication and authorization enabled.