Further Elixir Client Improvements

Created by: halostatue

Attention to @wing328 and @mrmstn.

Resolves #12731 (closed) 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 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.