Add operation level servers support for java okhttp-gson client

[ajrice6713]

Add operation level server support for Java okhttp-gson http client

Closes #10847

At the API level - user can specify a custom base URL. If no custom base url is specified, the API selects the 1st path level server (if any), unless a different host index is specified. If no operation level servers are defined, the http request is built using the spec default server url.

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.

@bbdouglas @sreeshas @jfiala @lukoyanov @cbornet @jeff9finger @karismann @Zomzog @lwlee2608 @nmuesch

[wing328]

LGTM. We'll add a test or 2 later when we update the samples to use OAS 3.0 spec.

[Philipp-Borchert-ISH]

Hi @wing328 / @ajrice6713 - this caused breaking changes in generated code (ApiClient::buildCall/buildRequest etc) - furthermore the necessary code migration is a bit odd because the new parameter for these methods is not documented in the generated javadoc.
Just two remarks:

1. Shouldn't this have been part of 5.4.x instead of patch 5.3.1? That's how I interpret https://openapi-generator.tech/docs/release-summary/ at least
2. Maybe javadoc for the baseUrl should be added, it seems to be optional/nullable

[ajrice6713]

Hey @Philipp-Borchert-ISH

Can you provide the error snippet of whats broken in the buildCall function? It wasnt intended to be breaking (and worked in my testing) 😢

[Philipp-Borchert-ISH]

Hi @ajrice6713, I'm referring to a "breaking" API change, not a bug in your code :-)
Specifically the "baseUrl" parameter has been added on multiple public methods, which breaks compatibility with code accessing these methods. I reckon that shouldn't be allowed in patch releases, hence the question to William.

[wing328]

@Philipp-Borchert-ISH very good question. From what I understand, a developer shouldn't be calling these buildSomething methods directly and therefore when they use a newer version of the Java SDK generated with this particular enhancement (PR), they shouldn't need to update their code and it should work as usual.

Do you mind elaborating a bit more on your use cases that require calling these buildSomething method directly?

[Philipp-Borchert-ISH]

Hi @wing328, we're using them primarily in artificial test cases to generate "bad" requests to validate server side error handling in our APIs - so it's probably an edge case.

a developer shouldn't be calling these buildSomething methods directly

I guess this is a bit of a tricky situation - the generated clients the developers "should" be using are exposing getters/setters and a constructor including the ApiClient class, so right now it is not obvious to developers (both providing + consuming SDKs) that they should not actually use it. Other classes / interfaces in the same package - e.g. ApiCallback or ApiException - are essential to the generated API clients as well. I think it would be beneficial for the future to have a clear distinction between "this is public -> it's an API" vs. "this should not be public -> shouldn't be visible" (visible as in access modifier).

Thx for the quick feedback btw!