Generated models and types should follow Swift conventions

[PadraigK]

The casing of names in the generated code should match normal Swift coding standards, e.g. properties should be camelCase and types should be PascalCase.

From reading the principles, I understand that the generator wants to be true to whatever is in the spec and the general guidance is that we should build tools around the generator to customize things. I also understand that implementing this in the generator could lead to naming collisions in certain cases. However, without this feature, it would be hard to justify migrating a code base from a generator that does camelCase names to this one.

Some things I've considered:

• Preprocessing the spec: This won’t work, since the models need to serialize back to the exact original in the spec or generated JSON will be wrong and the server side would fail.
• Change the spec: This would be too disruptive. It would force the clients using other languages to adopt Swift coding standards. Many users don't control their specs.
• Writing custom models and mapping everything from the server into them: This would also be a large amount of busy-work and a maintenance headache, as well as a runtime cost.

Ideally this would be a setting or even the default. The generator could detect collisions and throw an obvious error. I'm also open to trying any work arounds that I haven't considered here.

[simonjbeaumont]

Thanks for taking the time to write up your considered position on this @PadraigK. This kind of feedback is super valuable, and is one of the reasons we want to make some of these decisions with the community, before releasing 1.0.

As you noted, we spent quite some time reasoning about the current position¹, which you took the time to read 🙏.

Currently the functions that make API calls match the operation IDs in the OpenAPI document, modulo some attempts to make them legal Swift names.

We're aware that there's some limitations in this area and this discussion is closely related to the current work being discussed in #95.

Ideally this would be a setting or even the default. The generator could detect collisions and throw an obvious error. I'm also open to trying any work arounds that I haven't considered here.

When thinking more about #95, I've been considering an alternative approach which might pave the way for something close to your suggestion.

The generator pipeline is currently:

1. Parse OpenAPI document from file.
2. Translate parsed OpenAPI document to intermediate representation.
3. Render intermediate representation as code.

I'm thinking that we could have a "preflight" step between (1) and (2), which would check if there are problematic identifiers and bail.

This would then be paired with a new feature that adds a mapping for keys and values in the OpenAPI document to the generator config file.

In this hypothetical future, we could switch to camel-casing operations, because we could detect whether this would result in a conflict at the pre-flight step and bail if-so.

This whole topic (of how we Swift-ify parts of the OpenAPI document) has the potential to be contentious, and will certainly result in an API change in the generated code, so we're taking it cautiously.

/cc others who have been involved here (mostly those who have commented on the proposal): @czechboy0 @denil-ct @FranzBusch @adam-fowler

Footnotes

1. https://swiftpackageindex.com/apple/swift-openapi-generator/0.1.3/documentation/swift-openapi-generator/project-scope-and-goals#Principle-Faithfully-represent-the-OpenAPI-document ↩

[denil-ct]

This is what I was thinking of as well. We could handle it in the generator as a last step for these illegal characters and generate some output reminiscent of the name in the spec. This would never satisfy everyone. If the user is not happy with the generated name, they can add a mapping of the path to the name they prefer in another file (perhaps the config file itself?).

We can even build on top of the JSON patch you mentioned @simonjbeaumont . Maybe adding custom operations? However it will be breaking the JSON patch spec. In that way we can handle two birds with one stone.

[FranzBusch]

In general, I understand the desire to have names that feel Swifty; however, I agree with @simonjbeaumont that we have to be careful how we do this without making both the plugin to complicated to maintain and trying to cater to every possible remapping. Additionally, this opens up another angle for changes to the generated code that are outside of the API authors control which can lead to another set of breaking changes for code using the generated interfaces.

As a rule of thumb, it is recommended to never expose these types publicly across library boundaries unless you control both sides and can evolve them together.

[czechboy0]

For folks interested in this issue being addressed, please chime in this issue: #112

[czechboy0]

Closing this one, please chime in #112 if you'd like this addressed.

[czechboy0]

Landed in 1.6.0 as idiomatic naming strategy: https://swiftpackageindex.com/apple/swift-openapi-generator/main/documentation/swift-openapi-generator/soar-0013