[JAVA e.g. feign] Need a common interface for generated ApiClient classes

Description

Currently, every time you generate client code in Java for a Swagger API, the ApiClient class that is generated will be an entirely different fully qualified class name (FQCN) and there is no common interface indicating what you can do with these objects.

In general, what you can do with an ApiClient could be different for each library e.g. feign may support different options than resteasy or jersey2.

We want the ability to have some shared code for configuring these ApiClient objects. Unless we want to use reflection for every call (which is brittle, annoying, and potentially slow if we are creating a new client for every HTTP request), we need some common interface.

We unfortunately can't just package the common interface in the generated code; it has to have a constant package name. Why not? Suppose microservice A depended on client libs from microservice B and microservice C, then it would get the same FQCN from maven from both generated client libraries (the FQCN of the common interface)!

Thus, the only real solution is to define a new module somewhere in this project that has these common interfaces. I think it makes the most sense to define a new module for each java library type, so that we don't pollute the generated code with dependencies they don't need.

Swagger-codegen version

2.3.0-SNAPSHOT

Swagger declaration file content or url

n/a this happens for any swagger.json. The ApiClient class in the generated code maven module has no base interface.

Command line used for generation

config.json:

{
  "library": "feign",
  "artifactId": "${CLIENT_LIB_ARTIFACT_ID}",
  "groupId": "${SERVICE_GROUP_ID}",
  "artifactVersion": "${VERSION}"
}

java -jar swagger-codegen-cli.jar \
  generate -i swagger.json \
  -l java \
  -o client_lib \
  -c config.json \
  --api-package "${CLIENT_LIB_PACKAGE}.api" \
  --model-package "${CLIENT_LIB_PACKAGE}.model" \
  --invoker-package ${CLIENT_LIB_PACKAGE}

Steps to reproduce

Look at the output code! The ApiClient class doesn't extend anything! :-)

Related issues/PRs

This is related - https://github.com/swagger-api/swagger-codegen/issues/6414
The solution they suggest is to copy all the template files from the resources folder and modify them manually.

This is possible, but not very practical since we'd have to maintain custom templates each time they change in the swagger project. We are generating the API clients on every build of our code by downloading the swagger JAR. It would be much preferred if the swagger clients had a base class out-of-the-box.

Suggest a fix/enhancement

I'm about to put up a PR, I would suggest we make new modules in this project that are very tiny maven modules with nothing but minimal dependencies and the common interface for a given Java library binding.

Start with the Java library templates in the resources folder and inspect the generated ApiClient produced by the provided feign configuration and command. Define the minimal per-library module and interface structure, then verify that generated clients expose the shared contract without adding unrelated dependencies.