Hi folks, here's a quick update on this proposal.
The review period ran until July 10 and produced a number of different ideas of how to address the motivating problem of this proposal, producing non-conflicting names in Swift from more flexible names in OpenAPI documents.
We didn't reach convergence, so we will put this proposal on hold for now.
The extra time will be used to explore a related idea, which could help provide a powerful customization point: a plugin for the Swift OpenAPI Generator itself, which would allow adopters to customize the logic of turning OpenAPI names into Swift names. This customization would be opt-in, but by default, we could use a mapping that avoids conflicts, even if it doesn't produce the prettiest names.
Please provide your thoughts in this issue, or start dedicated threads with pitches here on the forums, and add the openapi tag.
For next steps, we will come back to this proposal once we've explored the plugin idea, as whether there is a flexible customization point strongly influences the design of the default naming logic.
1 Like
Hi folks – another update on this proposal.
In order to understand the impact of this name mapping on readability and potential conflicts, I collected about 1200 real-world OpenAPI documents and performed experiments on them.
Here are some highlights:
- sample size: 1192
- experiment ran on them: the existing vs the proposed name mapping, from the original text of SOAR-0001
- number of conflict occurrences (might be multiple conflicts in a single OpenAPI doc) using the existing name mapping: 345
- number of conflict occurrences using the proposed name mapping in SOAR-0001: 0
So the newly proposed mapping reduces the number of conflicts in this test set from 345 to 0, while continuing to preserve readability and avoids modifying any identifies which are already valid Swift identifiers (which was a weakness of the double underscore-based idea).
In light of this data, I'd like to propose that we accept SOAR-0001 as-is, and I'm moving the proposal back into the In Review state until Thursday, July 27, 2023. Please provide any final feedback before then.
Note: The potential acceptance of this proposal does not affect the Generator plugin for customizing the OpenAPI -> Swift name creation idea, if a proposal to implement it is put forward, it'll still be evaluated on its own merits. The data above has just shown that there isn't a need to block SOAR-0001 on that more ambitious solution to conflicts, which don't seem to be a widespread problem with the new proposed mapping.
4 Likes
Since the additional review time did not produce any additional feedback, the proposal is moving forward to the state Ready for Implementation. At this point, we're waiting for a pull request with the implementation of this feature, including tests, and approvals from the maintainers.
Note that because this proposal will result in a breaking change, we will land it in a 0.1.x release under a feature flag, and will be enabled by default in 0.2.x.
The next steps:
- @Honza_Dvorsky will open a PR with a slight refactoring that propagates the feature flag storage to be accessible by this method
- once that lands, @denilchungath can pick up the in-progress PR and prepare it for review
Thanks everyone for the feedback and the discussion, it resulted in great new ideas that we might explore in the future!
2 Likes
SOAR-0001 landed in #89 and is now In Preview since the release 0.1.6, hidden behind the feature flag proposal0001.
It will become the default behavior in 0.2.0.