[Java][Feign] Expose response headers for feign client

Created by: hugo-ma-alves

Hello

The objective of this PR is to add the possibility of exposing the response Headers of the request on the feign clients. This is useful for some situations where the client needs to access information that it is contained on the response headers, for example, headers related with pagination, or resource location after creating a new resource.

I've created a new property called "exposeResponseHeaders", that by default is false, so if it is not defined we keep the same behavior as we have now. If this property is active the response is wrapped in a new class HttpResponse. This class contains the headers map and the body decoded by jackson to the correct type.

Example of a generated client:

package org.openapitools.client.api;

import org.openapitools.client.ApiClient;
import org.openapitools.client.EncodingUtils;
import org.openapitools.client.model.HttpResponse;

import org.openapitools.client.model.Order;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import feign.*;

public interface StoreApi extends ApiClient.Api {


 /**
  * Delete purchase order by ID
  * For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
  * @param orderId ID of the order that needs to be deleted (required)
  * @return HttpResponse<Void>
  */
 @RequestLine("DELETE /store/order/{orderId}")
 @Headers({
   "Accept: application/json",
 })
 HttpResponse<Void> deleteOrder(@Param("orderId") String orderId);

 /**
  * Returns pet inventories by status
  * Returns a map of status codes to quantities
  * @return HttpResponse&lt;Map&lt;String, Integer&gt;&gt;
  */
 @RequestLine("GET /store/inventory")
 @Headers({
   "Accept: application/json",
 })
 HttpResponse<Map<String, Integer>> getInventory();

 /**
  * Find purchase order by ID
  * For valid response try integer IDs with value &lt;&#x3D; 5 or &gt; 10. Other values will generated exceptions
  * @param orderId ID of pet that needs to be fetched (required)
  * @return HttpResponse&lt;Order&gt;
  */
 @RequestLine("GET /store/order/{orderId}")
 @Headers({
   "Accept: application/json",
 })
 HttpResponse<Order> getOrderById(@Param("orderId") Long orderId);

 /**
  * Place an order for a pet
  * 
  * @param order order placed for purchasing the pet (required)
  * @return HttpResponse&lt;Order&gt;
  */
 @RequestLine("POST /store/order")
 @Headers({
   "Content-Type: application/json",
   "Accept: application/json",
 })
 HttpResponse<Order> placeOrder(Order order);
}

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• Run the following to build the project and update samples:

  ./mvnw clean package 
  ./bin/generate-samples.sh
  ./bin/utils/export_docs_generators.sh

  Commit all changed files. This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master. These must match the expectations made by your contribution. You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*. For Windows users, please run the script in Git BASH.
• File the PR against the correct branch: master (5.3.0), 6.0.x
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

@wing328 @bbdouglas (2017/07) @sreeshas (2017/08) @jfiala (2017/08) @lukoyanov (2017/09) @cbornet (2017/09) @jeff9finger (2018/01) @karismann (2019/03) @Zomzog (2019/04) @lwlee2608 (2019/10) @nmuesch (2021/01)