OpenAPITools / OpenAPITools/openapi-generator
[DOCUMENTATION][SWIFT] Unclear documentation for library parameter in swift5 client
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Description
I was trying to generate an API client library using swift5, and I wanted it to use Alamofire library for that, as I saw it was possible in the page with the configuration parameter "library" and value "alamofire".
As reported by the documentation here, it should be possible to pass config options to the generator as "additional properties", so I tried to generate the API like this:
openapi-generator generate -i games.yaml -g swift5 -o gamesApi --additional-properties=library=alamofire
This generated the API, but without using Alamofire. I tried also using the alternative version:
openapi-generator generate -i games.yaml -g swift5 -o gamesApi -p library=alamofire
Same result. I also tried to add the parameter to a config file containing:
additionalProperties:
library: alamofire
But still nothing.
Only after some time, I stumbled upon an issue here on github where the parameter was passed differently:
openapi-generator generate -i games.yaml -g swift5 -o gamesApi --library alamofire
This finally worked like charm, but only after quite some frustration. I can imagine that probably this is the standard way of using the "library" parameter, but it was definitely unclear to me just reading the documentation and the list of configuration options for swift5.
openapi-generator version
Openapi-generator CLI version 5.1.0 (but same result with latest available snapshot)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/generators/swift5.md and the configuration documentation linked in the issue. Compare the documented library and additional-properties syntax with the working --library alamofire command. Done means the Swift 5 documentation clearly explains how to select Alamofire and avoids implying that the other forms have the same effect.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, swift
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100