Further Elixir Client Improvements

[halostatue]

Attention to @wing328 and @mrmstn.

Resolves #12731 and is the completion of the work that I started with #12751.

The changes here are extensive and likely resolve an issue that I have seen with the Ory SDK (ory/sdk#194). I have also been unable to run the integration suite for Elixir as I am (trying) to run everything in Docker (./run-in-docker.sh) as I do not have a suitable Java development environment set up, and do not do enough Java work to really justify it.

• Updated the README for Elixir projects. Aside from some improved readability of the template by use of link references instead of inline links, I have also fixed the examples:

  • The deps example should have been putting a version constraint related to appVersion.

  • The config example should have been using packageName instead of appName. This particular issue repeats.

• In all Elixir files:

  • Changed the function @docs formatting:

    • changed the ehading level for Parameters and Returns to h3 (### instead of ##). This will make somewhat better looking documentation that does not over-emphasize these details (which are not documented in a normal Elixir way, but this is somewhat to be expected with a code generator.) It may be desirable, after testing, to change this to h4 instead of h3.

    • Put parameter names and most return types in in-line code blocks (`hello`).

    • Put return types, when there are multiple types, in a Markdown list.

  • Fixed a lot of the spacing. Most files will be closer to Elixir standard formatting than they were. Because of the limitations of Mustache, it is still recommended that people who generate Elixir clients run mix format at least once on their codebase.

• api.mustache:

  • Removed an awkward function pipeline call. If we specified at least Elixir 1.12 (something that I do not recommend as we have recently jumped from requiring Elixir 1.6 to Elixir 1.10), there is a better way to specify this now with Kernel.then/2. In the meantime, assigning the constructed request structure to a variable and then making a separate pipeline for the request execution and handling makes for much easier to read generated code.

  • Fixed the extra space issue with evaluate_response call tuple values; {{=<% %>=}} changes the tag types, so this change is intentional.

• In config.exs.mustache, runtime.exs.mustache, mix.exs.mustache, and connection.ex.mustache, use packageName instead of appName for configuration specification. If packageName and appName differed, we would end up with cases like clients/client/elixir refers to an unavailable application ory/sdk#194.

• connection.ex.mustache has been almost entirely rewritten. The changes started in order to eliminate a @doc compile-time warning, but shifted to remove the old way of building Tesla client structs with use Tesla. It works, but is no longer the recommended way of building Tesla clients.

  • The recommended way of building a Tesla Client would now be Tesla.client(Connection.middleware(), Connection.adapter()).

  • Exposed both Connection.adapter/0 and Connection.middleware/1 for use. Connection.middleware/1 has special handling for the cases where OAuth2 or HTTP Basic Auth are defined in the application, but do not currently handle any other auth methods.

• deserializer.ex.mustache has mostly been reformatted. There are things that I do not like about it (I do not like pipelines with one line), and I have expanded one function capture into an anonymous function for readability.

• request_builder.ex.mustache has been updated with better function and parameter descriptions and names. Please note that if request |> method(:delete) |> method(:post) is supposed to produce a POST operation, we will need to change from Map.put_new/3 to Map.put/3.

  • Reordered evaluate_response/2 so that it is the function documented, and made decode/2 and response_mapping/3 private functions. As far as I can tell, I have not changed the functionality.

Both the sample project and the example generated project compile cleanly without warnings or errors.

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 (6.1.0) (minor release - breaking changes with fallbacks), 7.0.x (breaking changes without fallbacks)
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

[mrmstn]

Thank you very much for all your changes, looks like a lot of work work and I really appreciate it a lot.

As I'm still on holiday (till 2022-07-12) I was only able to do the review on my phone (which isn't great, but better than nothing)

I've added some comments for discussion, overall I'm very happy with your changes and think they will add a lot of value to the generated clients, and the project itself.

@wing328 could you run the tests and give it another look?

[halostatue]

@mrmstn I think that this is something that can potentially wait until you’re back from vacation for a more in-depth review. I want to also look at the Elixir documentation to clarify a few things (such as the fact that, if you control the OpenAPI specification, you should customize the connection.ex file to your API—like with the Nomad client—and put it in the generator ignore file.

[mrmstn]

Hi @halostatue, thank you very much for your patient.
I had some time to continue my review and found some smaller things that should be fixed.

Please let me know if you have some questions according to my suggestions. Everything else looks really great, many thanks for your work!

[wing328]

@mrmstn any further feedback/question on this PR? shall we merge it?

[halostatue]

I’m fine with whatever, but it will probably take me a couple of days to respond for the next week, as I’ve got some other work that I’m finishing up.

[mrmstn]

@wing328 Thank you very much for the bump, I wasn't aware that I'm the blocker 🙈

Everything looks great and can be merged! @halostatue Thank you very much for your contribution

[neilberkman]

Looking forward to getting this merged. Any ETA on this?

[mrmstn]

@wing328 What's the further proceeding? Is there anything missing?

[wing328]

Sorry I missed it. Just merged.

[wing328]

@mrmstn when you've time, can you please PM me via Slack?

https://join.slack.com/t/openapi-generator/shared_invite/zt-12jxxd7p2-XUeQM~4pzsU9x~eGLQqX2g