Elixir: Improve generated API options docs (#13478)

While working with the Magento 2.4 API definition, there were several
issues found. The easiest to resolve is a documentation naming issue.
(The others will be raised for discussion.)

This is known to be an issue with query parameters, but may not be
limited to *just* query parameters.

In the event that a parameter is a mix of arrays and objects, the
template in the documentation for the API function was expanding out the
parameter name such that `foo[0]` would be turned into
`:foo_left_square_bracket0_right_square_bracket`, but the actual
parameter name was being left as `:foo[0]`, which meant that the
documentation did not reflect the actual parameter.

> Note: there are issues with the way that query parameters are put
> together in this sense, which is going to require substantially more
> work to resolve as well as discussion on how these options should be
> implemented, as what the Magento API requires may not be what is
> expected by a different server, and the nature of the input parameters
> is itself incorrect.
This commit is contained in:
Austin Ziegler 2022-09-26 05:34:44 -04:00 committed by GitHub
parent efccc01911
commit de745a4c61
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 6 additions and 6 deletions

View File

@ -29,7 +29,7 @@ defmodule {{moduleName}}.Api.{{classname}} do
- `:body` ({{dataType}}): {{&description}} - `:body` ({{dataType}}): {{&description}}
{{/isBodyParam}} {{/isBodyParam}}
{{^isBodyParam}} {{^isBodyParam}}
- `{{#atom}}{{#underscored}}{{&paramName}}{{/underscored}}{{/atom}}` ({{&dataType}}): {{&description}} - `{{#atom}}{{&baseName}}{{/atom}}` ({{&dataType}}): {{&description}}
{{/isBodyParam}} {{/isBodyParam}}
{{/optionalParams}} {{/optionalParams}}

View File

@ -45,8 +45,8 @@ defmodule OpenapiPetstore.Api.Fake do
- `connection` (OpenapiPetstore.Connection): Connection to server - `connection` (OpenapiPetstore.Connection): Connection to server
- `pet` (Pet): Pet object that needs to be added to the store - `pet` (Pet): Pet object that needs to be added to the store
- `opts` (keyword): Optional parameters - `opts` (keyword): Optional parameters
- `:query1` (String.t): query parameter - `:query_1` (String.t): query parameter
- `:header1` (String.t): header parameter - `:header_1` (String.t): header parameter
### Returns ### Returns
@ -386,7 +386,7 @@ defmodule OpenapiPetstore.Api.Fake do
- `:string` (String.t): None - `:string` (String.t): None
- `:binary` (String.t): None - `:binary` (String.t): None
- `:date` (Date.t): None - `:date` (Date.t): None
- `:date_time` (DateTime.t): None - `:dateTime` (DateTime.t): None
- `:password` (String.t): None - `:password` (String.t): None
- `:callback` (String.t): None - `:callback` (String.t): None

View File

@ -257,7 +257,7 @@ defmodule OpenapiPetstore.Api.Pet do
- `connection` (OpenapiPetstore.Connection): Connection to server - `connection` (OpenapiPetstore.Connection): Connection to server
- `pet_id` (integer()): ID of pet to update - `pet_id` (integer()): ID of pet to update
- `opts` (keyword): Optional parameters - `opts` (keyword): Optional parameters
- `:additional_metadata` (String.t): Additional data to pass to server - `:additionalMetadata` (String.t): Additional data to pass to server
- `:file` (String.t): file to upload - `:file` (String.t): file to upload
### Returns ### Returns
@ -297,7 +297,7 @@ defmodule OpenapiPetstore.Api.Pet do
- `pet_id` (integer()): ID of pet to update - `pet_id` (integer()): ID of pet to update
- `required_file` (String.t): file to upload - `required_file` (String.t): file to upload
- `opts` (keyword): Optional parameters - `opts` (keyword): Optional parameters
- `:additional_metadata` (String.t): Additional data to pass to server - `:additionalMetadata` (String.t): Additional data to pass to server
### Returns ### Returns