Proposal revision v1.3 · apple/swift-openapi-generator@73fd986 (original) (raw)
`@@ -11,6 +11,7 @@ Introduce an alternative naming strategy for more idiomatic Swift identifiers, i
`
11
11
`- v1.0 (2024-11-27): Initial version
`
12
12
`- v1.1 (2024-11-28): Also handle "/", "{", and "}" for better synthesized operation names
`
13
13
`- v1.2 (2024-12-10): Treat "/" as a word separator and improve handling of the lowercasing of acronyms at the start of an identifier.
`
``
14
`+
- v1.3 (2024-12-17): Add "+" as a word separator, clarify that defensive strategy always post-processes the output of the idiomatic strategy, clarify that content type names also change with the idiomatic strategy
`
14
15
`- Issues:
`
15
16
`- [apple/swift-openapi-generator#112][issuePlugin]
`
16
17
`- [apple/swift-openapi-generator#107][issue1]
`
`@@ -54,11 +55,13 @@ Our priority was to support as many valid OpenAPI documents as possible. However
`
54
55
``
55
56
`We propose to introduce a second, opt-in naming strategy, which produces idiomatic Swift identifiers from arbitrary OpenAPI names, and a way to fully customize the conversion from an OpenAPI name to a Swift identifier using a string -> string map.
`
56
57
``
57
``
`-
For clarity, we'll refer to the existing naming strategy as the "defensive" naming strategy, and to the new proposed strategy as the "idiomatic" naming strategy. The names reflect the strengths of each strategy - the defensive strategy can handle any OpenAPI document and produce compiling Swift code, the idiomatic naming strategy produces prettier names, but does not work for all documents, and falls back to the defensive strategy when needed on a per-name basis.
`
``
58
`+
For clarity, we'll refer to the existing naming strategy as the "defensive" naming strategy, and to the new proposed strategy as the "idiomatic" naming strategy. The names reflect the strengths of each strategy - the defensive strategy can handle any OpenAPI document and produce compiling Swift code, the idiomatic naming strategy produces prettier names, but does not work for all documents.
`
58
59
``
59
60
`` Part of the new strategy is adjusting the capitalization, and producing UpperCamelCase names for types, and lowerCamelCase names for members, as is common in hand-written Swift code.
``
60
61
``
61
``
`-
This strategy will fall back to the defensive strategy if it encounters any invalid symbols in the identifier.
`
``
62
`+
This strategy will pre-process the input string, and then still apply the defensive strategy on the output, to handle any illegal characters that are no explicitly handled by the idiomatic strategy.
`
``
63
+
``
64
`+
The configurable naming strategy will affect not only general names from the OpenAPI document ([SOAR-0001][soar0001]), but also content type names (SOAR-0002).
`
62
65
``
63
66
`The second feature introduced as part of this proposal is a way to provide a string -> string map to fully override only specific OpenAPI names and provide their exact Swift identifiers. This is the ultimate escape hatch when both naming strategies fail to provide the desired result for the adopter.
`
64
67
``
`@@ -80,9 +83,10 @@ To get a sense for the proposed change, check out the table below that compares
`
80
83
`` | __user | __user | __User | __user |
``
81
84
`` | get/pets/{petId} Changed in v1.2 | get_sol_pets_sol__lcub_petId_rcub_ | GetPetsPetId | getPetsPetId |
``
82
85
`` | HTTPProxy Added in v1.2 | HTTPProxy | HTTPProxy | httpProxy |
``
``
86
`` +
| application/myformat+json Added in v1.3 | application_myformat_plus_json | - | applicationMyformatJson |
``
83
87
`` | order#123 | order_num_123 | order_num_123 | order_num_123 |
``
84
88
``
85
``
`` -
Notice that in the last example, since the OpenAPI name contains the pound (#) character, the idiomatic naming strategy falls back to the defensive naming strategy. In all the other cases, however, the resulting names are more idiomatic Swift identifiers.
``
``
89
`` +
Notice that in the last example, since the OpenAPI name contains the pound (#) character, the idiomatic naming strategy lets the defensive naming strategy handle the illegal character. In all the other cases, however, the resulting names are more idiomatic Swift identifiers.
``
86
90
``
87
91
`> Tip: For more examples, check out the updated test suite.
`
88
92
``
`@@ -104,10 +108,11 @@ The idiomatic naming strategy (check out the current code [here][impl], look for
`
104
108
`` - spaces ( , ASCII: 0x20)
``
105
109
`` - slashes (/, ASCII: 0x2f) Added in v1.1, changed meaning in 1.2
``
106
110
`` - curly braces ({ and }, ASCII: 0x7b and 0x7d) Added in v1.1
``
``
111
`` +
- pluses (
+, ASCII:0x2b) Added in v1.3
``
107
112
``
108
113
`` > Note: We let Swift.String.isLetter decide whether a character is a letter, which has the advantage of including letters in the non-ASCII range. Swift identifiers also support a wide range of alphanumeric characters.
``
109
114
``
110
``
`-
If the OpenAPI name includes any other characters, the idiomatic naming strategy falls back to the defensive naming strategy for that input string only.
`
``
115
`+
If the OpenAPI name includes any other characters, the idiomatic naming strategy lets the defensive strategy handle those characters.
`
111
116
``
112
117
`` There's a second special case for handling all uppercased names, such as NOT_AVAILABLE - if this situation is detected, the idiomatic naming strategy turns it into NotAvailable for types and notAvailable for members.
``
113
118
``
`@@ -155,6 +160,7 @@ With this proposal, we plan to abandon the ["naming extensions" idea][issuePlugi
`
155
160
`- Not changing anything, this was the status quo since 0.2.0, but adopters have made it clear that there is room to improve the naming strategy through the several filed issues linked at the top of the proposal, so we feel that some action here is justified.
`
156
161
``
157
162
`[soar0001]: https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/soar-0001
`
``
163
`+
`
158
164
`[issue1]: https://github.com/apple/swift-openapi-generator/issues/107
`
159
165
`[issue2]: https://github.com/apple/swift-openapi-generator/issues/503
`
160
166
`[issue3]: https://github.com/apple/swift-openapi-generator/issues/244
`