Skip to content
GitLab

Elixir: Improve generated API options docs

Merged Administrator requested to merge github/fork/halostatue/fix-elixir-documentation-error into master

Created by: halostatue

@mrmstn

While working with the Magento 2.4 API definition to generate an Elixir client, 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.

As a small drive-by fix, changed run-in-docker.sh to use set -euo pipefail instead of set -exo pipefail. The script does not need tracing turned on but should check for previously unreferenced variables. This makes the output of run-in-docker.sh slightly nicer.

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.