From fe3db532da918f60672bcaa445c959280260eb40 Mon Sep 17 00:00:00 2001 From: "art.dambrine" <2318827-art.dambrine@users.noreply.gitlab.com> Date: Thu, 25 Nov 2021 07:18:26 +0100 Subject: [PATCH] asciidoc documentation v0.3 --- TODO.md | 8 +- docs/getAllPartners/http-response.adoc | 56 ++++++- docs/partnerapi.adoc | 219 ++++++++++++++++++++++++- 3 files changed, 268 insertions(+), 15 deletions(-) diff --git a/TODO.md b/TODO.md index 1764193..5b37abc 100644 --- a/TODO.md +++ b/TODO.md @@ -24,14 +24,14 @@ Date : 23-24 nov 2021 - [x] 6. The application will have a health check endpoint -- [ ] 7. The application will have suitable functional tests, checking real http functionality +- [x] 7. The application will have suitable functional tests, checking real http functionality - [x] 8. No authentication/security necessary -- [ ] This document will contain the specification of the REST endpoint, with data definition and error payload specification. +- [x] This document will contain the specification of the REST endpoint, with data definition and error payload specification. You should document how to -- [ ] Run the test suite -- [ ] Run application +- [x] Run the test suite +- [x] Run application - [ ] Optionally, a commentary on how you would deploy it (not necessary to implement this) \ No newline at end of file diff --git a/docs/getAllPartners/http-response.adoc b/docs/getAllPartners/http-response.adoc index 310533f..c0e379d 100644 --- a/docs/getAllPartners/http-response.adoc +++ b/docs/getAllPartners/http-response.adoc @@ -2,7 +2,59 @@ ---- HTTP/1.1 200 OK Content-Type: application/json -Content-Length: 1360 +Content-Length: 1359 -[{"id":1,"name":"B2boost","reference":"FYI1","locale":"en_BE","expirationTime":"2022-11-24 17:46:00+01"},{"id":2,"name":"Proximus","reference":"FYI2","locale":"en_BE","expirationTime":"2022-11-24 17:46:00+01"},{"id":3,"name":"KBC Bank","reference":"FYI3","locale":"en_BE","expirationTime":"2022-11-24 17:46:00+01"},{"id":4,"name":"AB InBev","reference":"FYI4","locale":"en_BE","expirationTime":"2022-11-24 17:46:00+01"},{"id":5,"name":"Spotify","reference":"FYI5","locale":"sv_SE","expirationTime":"2022-11-24 17:46:00+01"},{"id":6,"name":"AMSOM-Habitat","reference":"FYI6","locale":"fr_FR","expirationTime":"2022-11-24 17:46:00+01"},{"id":7,"name":"Microsoft","reference":"FYI7","locale":"en_US","expirationTime":"2022-11-24 17:46:00-04"},{"id":8,"name":"Sony","reference":"FYI8","locale":"ja_JP","expirationTime":"2022-11-24 17:46:00+09"},{"id":9,"name":"Intel","reference":"FYI9","locale":"en_US","expirationTime":"2022-11-24 17:46:00-04"},{"id":10,"name":"Cisco","reference":"FYI10","locale":"en_US","expirationTime":"2022-11-24 17:46:00-04"},{"id":11,"name":"Dell","reference":"FYI11","locale":"en_US","expirationTime":"2022-11-24 17:46:00-04"},{"id":12,"name":"Canonical","reference":"FYI12","locale":"en_US","expirationTime":"2022-11-24 17:46:00-04"},{"id":13,"name":"UPS","reference":"FYI25","locale":"en_BE","expirationTime":"2013-10-03 12:18:46+01"}] +{ + "content": [ + { + "id": 1, + "name": "B2boost", + "reference": "FYI1", + "locale": "en_BE", + "expirationTime": "2022-11-24 17:46:00+01" + }, + { + "id": 2, + "name": "Proximus", + "reference": "FYI2", + "locale": "en_BE", + "expirationTime": "2022-11-24 17:46:00+01" + }, + + // more json elements... + + { + "id": 10, + "name": "Cisco", + "reference": "FYI10", + "locale": "en_US", + "expirationTime": "2022-11-24 17:46:00-04" + } + ], + "pageable": { + "sort": { + "empty": true, + "sorted": false, + "unsorted": true + }, + "offset": 0, + "pageNumber": 0, + "pageSize": 10, + "paged": true, + "unpaged": false + }, + "totalPages": 2, + "totalElements": 12, + "last": false, + "size": 10, + "number": 0, + "sort": { + "empty": true, + "sorted": false, + "unsorted": true + }, + "first": true, + "numberOfElements": 10, + "empty": false +} ---- \ No newline at end of file diff --git a/docs/partnerapi.adoc b/docs/partnerapi.adoc index 10a499a..163f83d 100644 --- a/docs/partnerapi.adoc +++ b/docs/partnerapi.adoc @@ -30,7 +30,41 @@ _Credits (Purpose section) : B2Boost_ In the following document you will find a simple documentation of the API. Most of the following sections have been generated with https://spring.io/projects/spring-restdocs[Spring Rest Docs]. -=== Accessing all the partners GET +== The partner resource + + +|=== +|Field |Type |Semantics |Example + +|id +|long +|The database id of the partner +|1 + +|name +|string +|"The name of the partner" +|"B2Boost" + +|reference +|string +|The unique reference of the partner +|"xxxxx" + +|locale +|string +|A valid Locale of the partner +|"en_BE" + +|expirationTime +|string +|The ISO-8601 UTC date time when the partner is going to expire +|"2022-11-24 17:46:00+01:00" + +|=== + + +=== Accessing all the partners GET endpoint A `GET` request is used to access all the partners read. ==== Request structure @@ -40,11 +74,31 @@ include::./getAllPartners/http-request.adoc[] ==== Example response include::./getAllPartners/http-response.adoc[] +NOTE: response body within content json array and pagination infos within pageable json object + ==== CURL request include::getAllPartners/curl-request.adoc[] +==== Pagination parameters -=== Accessing the partner GET +.+/partners+ +|=== +|Parameter|Description + +|`+from+` +|offset in the resultset to paginate to (default value is 0) +|`+size+` +|Window pagination size (default value is 10) +|=== + +==== Exemple CURL request with pagination parameters +[source,bash] +---- +$ curl --location --request GET 'http://localhost:8080/partners?from=0&size=4' +---- + + +=== Accessing the partner GET endpoint A `GET` request is used to access the partner read. ==== Request structure @@ -59,8 +113,38 @@ include::getAPartner/http-response.adoc[] ==== CURL request include::getAPartner/curl-request.adoc[] +==== Example GET request with errors +===== Example with invalid value for id +[source,bash] +---- +$ curl --location --request GET 'http://localhost:8080/partner/-1' +---- +Response +[source,json] +---- +{ + "code": 500, + "message": "getPartnerById.Id: must be greater than or equal to 1" +} +---- +NOTE: The Min value for id is 1 + +===== Example partner not found +[source,bash] +----- +$ curl --location --request GET 'http://localhost:8080/partner/3000' +----- +Response +[source,json] +---- +{ + "code": 404, + "message": "Partner with id 3000 not found!" +} +---- + -=== Accessing the partner POST +=== Accessing the partner POST endpoint A `POST` request is used to add a partner resource. ==== Request structure @@ -72,7 +156,52 @@ include::createPartner/http-response.adoc[] ==== CURL request include::createPartner/curl-request.adoc[] -=== Accessing the partner PUT +==== Example POST request with errors +===== Example with error on create with wrong date format +[source,bash] +----- +$ curl --location --request POST 'http://localhost:8080/partner' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "UPS", + "reference": "FYI15", + "locale": "en_BE", + "expirationTime": "2017-10-03T12:18:46" +}' +----- +Response +[source,json] +---- +{ + "code": 400, + "message": "Date 2017-10-03T12:18:46 is an invalid ISO-8601 UTC date time! Should be something like 2017-10-03T12:18:46+00:00" +} +---- +NOTE: Here the UTC timezone is missing + +===== Example with error on create with invalid locale +[source,bash] +----- +$ curl --location --request POST 'http://localhost:8080/partner' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "UPS", + "reference": "FYI15", + "locale": "en_BEE", + "expirationTime": "2017-10-03T12:18:46+08:00" +}' +----- +Response +[source,json] +---- +{ + "code": 400, + "message": "Locale en_BEE is an invalid Locale!" +} +---- +NOTE: Here the locale should be en_BE + +=== Accessing the partner PUT endpoint A `PUT` request is used to update a partner resource. ==== Request structure @@ -84,7 +213,54 @@ include::./updatePartner/http-response.adoc[] ==== CURL request include::./updatePartner/curl-request.adoc[] -=== Accessing the partner DELETE +==== Example PUT request with errors +The errors for validating locale and date are the same between PUT and POST + +===== Example with error on update with not unique reference +[source,bash] +----- +$ curl --location --request PUT 'http://localhost:8080/partner/1' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "UPS", + "reference": "FYI5", + "locale": "en_US", + "expirationTime": "2022-05-23T12:18:46-05:00" +}' +----- +Response +[source,json] +---- +{ + "code": 500, + "message": "could not execute statement; SQL [n/a]; constraint [\"PUBLIC.CONSTRAINT_INDEX_7 ON PUBLIC.PARTNERS(REF) VALUES 5\"; SQL statement:\nupdate partners set expires=?, locale=?, company_name=?, ref=? where id=? [23505-200]]; nested exception is org.hibernate.exception.ConstraintViolationException: could not execute statement" +} +---- +NOTE: The reference attribute is configured to be a unique identifier for the partner + +===== Example with error on update with partner not found +[source,bash] +----- +$ curl --location --request PUT 'http://localhost:8080/partner/4000' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "UPS", + "reference": "FYI50", + "locale": "en_US", + "expirationTime": "2022-05-23T12:18:46-05:00" +}' +----- +Response +[source,json] +---- +{ + "code": 404, + "message": "Partner with id 4000 not found!" +} +---- + + +=== Accessing the partner DELETE endpoint A `DELETE` request is used to delete the partner. ==== Request structure @@ -99,10 +275,35 @@ include::./deletePartner/http-response.adoc[] ==== CURL request include::./deletePartner/curl-request.adoc[] +==== Example DELETE request with errors +===== Example with error on update with with partner not found +[source,bash] +----- +$ curl --location --request DELETE 'http://localhost:8080/partner/2000' +----- +Response +[source,json] +---- +{ + "code": 404, + "message": "Partner with id 2000 not found!" +} +---- + -== Conseils de déploiement -Build le jar pour le deploiement : +== Usefull commands +_Assuming you are using a bash cli_ + +=== Run the app in dev env +---- +./gradlew bootRun +---- +=== Run the test suite with gradle +---- +./gradlew test +---- +=== Prepare the jar archive with gradle for deployment ---- -gradle clean bootJar +./gradlew clean bootJar ---- -NOTE: build/libs/monjardeproduction.jar \ No newline at end of file +NOTE: Path of the output is `build/libs/api-spring-gradle-b2boost-0.0.1-SNAPSHOT.jar` \ No newline at end of file