Further Elixir Client Improvements (#12775)

* Further Elixir Client Improvements

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 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.

* Address issues found in code review

- The example dependency code in the README had dropped the opening
  brace for the tuple. This has been resolved.

- The default formatting of the API pipelines has been adjusted to
  minimize possible changes from `mix format`.

* Update modules/openapi-generator/src/main/resources/elixir/api.mustache

Co-authored-by: Michael Ramstein <633688+mrmstn@users.noreply.github.com>

* Update modules/openapi-generator/src/main/resources/elixir/connection.ex.mustache

Co-authored-by: Michael Ramstein <633688+mrmstn@users.noreply.github.com>

* Update modules/openapi-generator/src/main/resources/elixir/connection.ex.mustache

Co-authored-by: Michael Ramstein <633688+mrmstn@users.noreply.github.com>

* Update templates based on review comments

Co-authored-by: Michael Ramstein <633688+mrmstn@users.noreply.github.com>

Author: halostatue

modules/openapi-generator/src/main/resources/elixir/README.md.mustache

@@ -2,33 +2,46 @@
 
 {{appDescription}}
 
-### Building
+## Building
 
 To install the required dependencies and to build the elixir project, run:
-```
+
+```console
 mix local.hex --force
 mix do deps.get, compile
 ```
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `{{#underscored}}{{packageName}}{{/underscored}}` to your list of dependencies in `mix.exs`:
+If [available in Hex][], the package can be installed by adding `{{#underscored}}{{packageName}}{{/underscored}}` to
+your list of dependencies in `mix.exs`:
 
 ```elixir
-def deps do
-  [{:{{#underscored}}{{packageName}}{{/underscored}}, "~> 0.1.0"}]
-end
+{{=<% %>=}}def deps do
+  [{<%#atom%><%#underscored%><%packageName%><%/underscored%><%/atom%>, "~> <%appVersion%>"}]
+end<%={{ }}=%>
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at [https://hexdocs.pm/{{#underscored}}{{packageName}}{{/underscored}}](https://hexdocs.pm/{{#underscored}}{{packageName}}{{/underscored}}).
-
+Documentation can be generated with [ExDoc][] and published on [HexDocs][]. Once published, the docs can be found at
+[https://hexdocs.pm/{{#underscored}}{{packageName}}{{/underscored}}][docs].
 
 ## Configuration
 
-You can override the URL of your server (e.g. if you have a separate development and production server in your configuration files.
+You can override the URL of your server (e.g. if you have a separate development and production server in your
+configuration files).
+
+```elixir
+config :{{#underscored}}{{packageName}}{{/underscored}}, base_url: "{{{basePath}}}"
+```
+
+Multiple clients for the same API with different URLs can be created passing different `base_url`s when calling
+`{{moduleName}}.Connection.new/1`:
+
 ```elixir
-config :{{#underscored}}{{appName}}{{/underscored}}, base_url: "{{{basePath}}}"
-```
+client = {{moduleName}}.Connection.new(base_url: "{{{basePath}}}")
+```
+
+[exdoc]: https://github.com/elixir-lang/ex_doc
+[hexdocs]: https://hexdocs.pm
+[available in hex]: https://hex.pm/docs/publish
+[docs]: https://hexdocs.pm/{{#underscored}}{{packageName}}{{/underscored}}

modules/openapi-generator/src/main/resources/elixir/api.mustache

@@ -6,9 +6,8 @@ defmodule {{moduleName}}.Api.{{classname}} do
 
   alias {{moduleName}}.Connection
   import {{moduleName}}.RequestBuilder
-
 {{#operations}}
-  {{#operation}}
+{{#operation}}
 
   @doc """
   {{#summary}}
@@ -18,25 +17,26 @@ defmodule {{moduleName}}.Api.{{classname}} do
   {{&notes}}
   {{/notes}}
 
-  ## Parameters
+  ### Parameters
 
-  - connection ({{&moduleName}}.Connection): Connection to server
+  - `connection` ({{&moduleName}}.Connection): Connection to server
 {{#requiredParams}}
-  - {{#underscored}}{{&paramName}}{{/underscored}} ({{&dataType}}): {{&description}}
+  - `{{#underscored}}{{&paramName}}{{/underscored}}` ({{&dataType}}): {{&description}}
 {{/requiredParams}}
-  - opts (KeywordList): [optional] Optional parameters
+  - `opts` (keyword): Optional parameters
 {{#optionalParams}}
 {{#isBodyParam}}
-    - :body ({{dataType}}): {{&description}}
+    - `:body` ({{dataType}}): {{&description}}
 {{/isBodyParam}}
 {{^isBodyParam}}
-    - {{#underscored}}:{{&paramName}}{{/underscored}} ({{&dataType}}): {{&description}}
+    - `{{#atom}}{{#underscored}}{{&paramName}}{{/underscored}}{{/atom}}` ({{&dataType}}): {{&description}}
 {{/isBodyParam}}
 {{/optionalParams}}
-  ## Returns
 
-  {:ok, {{#isArray}}[%{{&returnBaseType}}{}, ...]{{/isArray}}{{#isMap}}%{}{{/isMap}}{{^returnType}}nil{{/returnType}}{{#returnSimpleType}}{{#returnType}}{{{.}}}{{/returnType}}{{/returnSimpleType}}} on success
-  {:error, Tesla.Env.t} on failure
+  ### Returns
+
+  - `{:ok, {{#isArray}}[%{{&returnBaseType}}{}, ...]{{/isArray}}{{#isMap}}%{}{{/isMap}}{{^returnType}}nil{{/returnType}}{{#returnSimpleType}}{{#returnType}}{{{.}}}{{/returnType}}{{/returnSimpleType}}}` on success
+  - `{:error, Tesla.Env.t}` on failure
   """
   {{{typespec}}}
   def {{{operationId}}}(connection, {{#requiredParams}}{{#underscored}}{{{paramName}}}{{/underscored}}, {{/requiredParams}}{{^hasOptionalParams}}_{{/hasOptionalParams}}opts \\ []) do
@@ -52,29 +52,33 @@ defmodule {{moduleName}}.Api.{{classname}} do
 {{/isBodyParam}}
 {{#-last}}
     }
+
 {{/-last}}
 {{/optionalParams}}
-    %{}
-    |> method(:{{#underscored}}{{httpMethod}}{{/underscored}})
-    |> url("{{replacedPathName}}")
+    request =
+      %{}
+      |> method({{#atom}}{{#underscored}}{{httpMethod}}{{/underscored}}{{/atom}})
+      |> url("{{replacedPathName}}")
 {{#requiredParams}}
 {{^isPathParam}}
-    |> add_param({{#isBodyParam}}:body{{/isBodyParam}}{{#isFormParam}}{{#isMultipart}}{{#isFile}}:file{{/isFile}}{{^isFile}}:form{{/isFile}}{{/isMultipart}}{{^isMultipart}}:form{{/isMultipart}}{{/isFormParam}}{{#isQueryParam}}:query{{/isQueryParam}}{{#isHeaderParam}}:headers{{/isHeaderParam}}, {{#isBodyParam}}:body, {{/isBodyParam}}{{^isBodyParam}}{{#atom}}{{baseName}}{{/atom}}, {{/isBodyParam}}{{#underscored}}{{paramName}}{{/underscored}})
+      |> add_param({{#isBodyParam}}:body{{/isBodyParam}}{{#isFormParam}}{{#isMultipart}}{{#isFile}}:file{{/isFile}}{{^isFile}}:form{{/isFile}}{{/isMultipart}}{{^isMultipart}}:form{{/isMultipart}}{{/isFormParam}}{{#isQueryParam}}:query{{/isQueryParam}}{{#isHeaderParam}}:headers{{/isHeaderParam}}, {{#isBodyParam}}:body{{/isBodyParam}}{{^isBodyParam}}{{#atom}}{{baseName}}{{/atom}}{{/isBodyParam}}, {{#underscored}}{{paramName}}{{/underscored}})
 {{/isPathParam}}
 {{/requiredParams}}
 {{#optionalParams}}
 {{#-first}}
-    |> add_optional_params(optional_params, opts)
+      |> add_optional_params(optional_params, opts)
 {{/-first}}
 {{/optionalParams}}
 {{#requiresHttpcWorkaround}}
-    |> ensure_body()
+      |> ensure_body()
 {{/requiresHttpcWorkaround}}
-    |> Enum.into([])
-    |> (&Connection.request(connection, &1)).()
+      |> Enum.into([])
+
+    connection
+    |> Connection.request(request)
     |> evaluate_response({{#responses}}{{#-first}}[
 {{/-first}}
-      { {{& codeMappingKey}}, {{decodedStruct}}}{{^-last}},{{/-last}}
+      {{=<% %>=}}{<%& codeMappingKey%>, <%decodedStruct%>}<%={{ }}=%>{{^-last}},{{/-last}}
 {{#-last}}    ]{{/-last}}{{/responses}})
   end
   {{/operation}}

modules/openapi-generator/src/main/resources/elixir/config.exs.mustache

@@ -7,7 +7,7 @@
 # General application configuration
 import Config
 
-config :{{#underscored}}{{appName}}{{/underscored}}, base_url: "{{{basePath}}}"
+config {{#atom}}{{#underscored}}{{packageName}}{{/underscored}}{{/atom}}, base_url: "{{{basePath}}}"
 
 # Import environment specific config. This must remain at the bottom
 # of this file so it overrides the configuration defined above.