📝 Document logging

- document logging (example and config) - update release notes for 3.3.0 - replace search.maven.org with central.sonatype.com - replace Maven-specific instructions with a link to Maven central snippets - remove redundant hyperlinks
tomtom-international · Oct 20, 2023 · 036dc9b · 036dc9b
1 parent f0f94e7
commit 036dc9b
Showing 1 changed file with 39 additions and 45 deletions.
diff --git a/README.md b/README.md
@@ -22,8 +22,7 @@ limitations under the License.
 * [Intro](#intro)
 * [Changelog](#changelog)
 * [Usage](#usage)
-   * [Maven](#maven)
-* [Request examples](#requests)
+* [Request examples](#request-examples)
    * [Supported HTTP methods](#http-methods)
    * [A request to an arbitrary url](#url)
    * [Base url](#base-url)
@@ -38,12 +37,12 @@ limitations under the License.
    * [Response body](#response-body)
    * [Deserializing JSON responses to Java objects](#jsons)
    * [Deserializing JSON responses to Java generics](#generics)
+* [Logging](#logging)
 * [Future work](#todo)
 * [Known bugs](#bugs)
 * [Contact](#contact)
 * [Disclaimer](#disclaimer)
 
-<a id='intro'></a>
 ## Intro
 This client wraps around [Apache HttpClient](https://hc.apache.org/httpcomponents-client-ga/) and [Jackson Databind](https://github.com/FasterXML/jackson-databind) libraries providing lean Groovy syntax:
 ```groovy
@@ -87,55 +86,46 @@ class IceCreamTest {
 ```
 Full Java API reference is available [here](doc/JAVA.md)
 
-<a id='changelog'></a>
 ## Changelog
-**[(draft) 3.3.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/3.3.0/jar)**: (chore) migrate to [org.wiremock](https://central.sonatype.com/artifact/org.wiremock/wiremock) & [httclient5](https://central.sonatype.com/artifact/org.apache.httpcomponents.client5/httpclient5)
+**[3.3.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/3.3.0)**: 
+  * (feat) [logging](#logging)
+  * (chore) migrate to [org.wiremock](https://central.sonatype.com/artifact/org.wiremock/wiremock) & [httclient5](https://central.sonatype.com/artifact/org.apache.httpcomponents.client5/httpclient5)
 
-**[3.2.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/3.2.0/jar)**: (feat) default headers
+**[3.2.0](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/3.2.0)**: (feat) default headers
 
-**[3.1.1](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/3.1.1/jar)**: (security) remove vulnerable dependencies
+**[3.1.1](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/3.1.1)**: (security) remove vulnerable dependencies
 
-**[3.1.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/3.1.0/jar)**: (feat) query parameter support
+**[3.1.0](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/3.1.0)**: (feat) query parameter support
 
-**[3.0.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/3.0.0/jar)**: (chore) Groovy 4 and other dependency updates
+**[3.0.0](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/3.0.0)**: (chore) Groovy 4 and other dependency updates
 
-**[2.0.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/2.0.0/jar)**: (feature) Java-friendly API
+**[2.0.0](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/2.0.0)**: (feature) Java-friendly API
 
-**[1.4.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/1.4.0/jar)**: (chore) updated dependencies, including Groovy v2 -> v3 and Jackson (addressing [CVE-2019-17531](https://github.com/advisories/GHSA-gjmw-vf9h-g25v))
+**[1.4.0](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/1.4.0)**: (chore) updated dependencies, including Groovy v2 -> v3 and Jackson (addressing [CVE-2019-17531](https://github.com/advisories/GHSA-gjmw-vf9h-g25v))
 
-**[1.3.1](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/1.3.1/jar)**: (chore) updated dependencies, including jackson-databind version with vulnerabilities
+**[1.3.1](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/1.3.1)**: (chore) updated dependencies, including jackson-databind version with vulnerabilities
 
-**[1.3.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/1.3.0/jar)**: (feat) file upload
+**[1.3.0](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/1.3.0)**: (feat) file upload
 
-**[1.2.3](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/1.2.3/jar)**: (chore) updated dependencies, including jackson-databind version with vulnerabilities
+**[1.2.3](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/1.2.3)**: (chore) updated dependencies, including jackson-databind version with vulnerabilities
 
-**[1.2.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/1.2.0/jar)**: (feature) support for TRACE, OPTIONS and PATCH methods
+**[1.2.0](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/1.2.0)**: (feature) support for TRACE, OPTIONS and PATCH methods
 
-**[1.1.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/1.1.0/jar)**: (doc) maven usage and javadocs
+**[1.1.0](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/1.1.0)**: (doc) maven usage and javadocs
 
-**[1.0.0](https://search.maven.org/artifact/com.tomtom.http/goji-http-client/1.0.0/jar)**: initial release
+**[1.0.0](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/1.0.0)**: initial release
 
-<a id='usage'></a>
 ## Usage
 
 GOJI HTTP uses the [semantic versioning](http://semver.org/) strategy: MAJOR.MINOR.PATCH.
 
-<a id='maven'></a>
-### Maven
-
-```xml
-<dependency>
-    <groupId>com.tomtom.http</groupId>
-    <artifactId>goji-http-client</artifactId>
-    <version>3.2.0</version>
-</dependency>
-```
+Check [Maven central repository](https://central.sonatype.com/artifact/com.tomtom.http/goji-http-client/3.3.0) for snippets to add the client as a dependency for your build system.  
 
 <a id='requests'></a>
 ## Request examples
 
 <a id='http-methods'></a>
-### Supported HTTP methods:
+### Supported HTTP methods
 
 `GET`, `POST`, `PUT` and `DELETE` are supported:
 ```groovy
@@ -149,14 +139,13 @@ http.options()
 ```
 
 <a id='url'></a>
-### A request to an arbitrary url:
+### A request to an arbitrary url
 
 ```groovy
 http.get(url: 'http://pizza-delivery.org/margheritas')
 ```
 
-<a id='base-url'></a>
-### Base url:
+### Base url
 
 If you want to make a number of requests to a given service, you can specify the `baseUrl` constructor parameter:
 ```groovy
@@ -165,8 +154,7 @@ def http = new HttpClient(baseUrl: 'http://water-melon.com')
 http.get(path: '/slice')
 ```
 
-<a id='query'></a>
-### Query:
+### Query
 
 You can either specify a query in `url` or `path`, or via `query` parameter:
 
@@ -180,8 +168,7 @@ http.put(path: '/put', query: [some: 'query', other: ['one', 'two']])
 
 > _NB!_ if `url` or `path` contains a query already, `query` parameter is ignored.
 
-<a id='request-headers'></a>
-### Request headers:
+### Request headers
 
 ```groovy
 http.put(
@@ -191,8 +178,7 @@ http.put(
         'Content-Type': 'application/json'])
 ```
 
-<a id='default-headers'></a>
-#### Default headers:
+#### Default headers
 
 Default headers are sent with each request. It is also possible to override default headers per request: 
 
@@ -203,8 +189,7 @@ def http = new HttpClient(defaultHeaders: [
 http.put(path: '/put', headers: ['Content-Type': 'application/xml'])
 ```
 
-<a id='request-body'></a>
-### Request body:
+### Request body
 
 Any non-string body is serialized as JSON.
 
@@ -243,7 +228,6 @@ def response = http.get(path: '/get')
 assert response.statusCode == ResponseCode.OK
 ```
 
-<a id='response-headers'></a>
 ### Response headers
 
 ```groovy
@@ -256,7 +240,6 @@ assert response.headers == [
     Connection: 'keep-alive'] 
 ```
 
-<a id='response-body'></a>
 ### Response body
 
 By default, the response body is a String:
@@ -301,12 +284,25 @@ assert response.body == [
 
 See more use-cases in [tests](src/test/groovy)
 
+## Logging
+
+The client uses [log4j v2](https://logging.apache.org/log4j/2.x/), sample output:
+```
+2023-09-23 14:54:20 INFO POST http://localhost:53611/freezer
+2023-09-23 14:54:20 INFO     headers: [shelve: top]
+2023-09-23 14:54:20 INFO     body: ice-cream
+2023-09-23 14:54:20 INFO => response: 200
+2023-09-23 14:54:20 INFO     headers: [Content-Type: application/json]
+2023-09-23 14:54:20 INFO     body: {"contents": ["ice-cream"]}
+```
+
+Example configuration can be found [here](./src/test/resources/log4j2.xml).
+
 <a id='todo'></a>
 ## Future work
 
 - Verify HTTPS certificates
 - Document URL encoding behavior
-- Allow specifying `Authorization` header in constructor
 
 <a id='bugs'></a>
 ## Known bugs
@@ -331,12 +327,10 @@ And release (when successful):
 mvn nexus-staging:release
 ```
 
-<a id='contact'></a>
 ## Contact
 
 [artamonov.kirill@gmail.com](mailto:artamonov.kirill@gmail.com)
 
-<a id="disclaimer"></a>
 ## Disclaimer
 
 Our primary use-case of this http client is testing our REST services. The client has not been tested for any production use though we don't expect big issues there.