OpenAPITools / OpenAPITools/openapi-generator

[DOCUMENTATION][SWIFT] Unclear documentation for library parameter in swift5 client

Open
#9,165 1 comment 3 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.