Idiomatic naming strategy as opt-in (#679)

### Motivation

Implementation of #683.

### Modifications

- Implemented the SOAR-0013 idiomatic naming strategy
- Added name overrides
- Switched most reference tests to use the new strategy
- Updated some docs (I'll update the rest after this lands and gets
released, then I can update Examples and IntegrationTest)

### Result

SOAR-0013 implemented.

### Test Plan

Updated and added new unit tests.

---------

Co-authored-by: Si Beaumont <simonjbeaumont@gmail.com>
Co-authored-by: Si Beaumont <beaumont@apple.com>

Author: czechboy0

Sources/_OpenAPIGeneratorCore/Config.swift

@@ -12,6 +12,20 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// A strategy for turning OpenAPI identifiers into Swift identifiers.
+public enum NamingStrategy: String, Sendable, Codable, Equatable {
+
+    /// A defensive strategy that can handle any OpenAPI identifier and produce a non-conflicting Swift identifier.
+    ///
+    /// Introduced in [SOAR-0001](https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/soar-0001).
+    case defensive
+
+    /// An idiomatic strategy that produces Swift identifiers that more likely conform to Swift conventions.
+    ///
+    /// Introduced in [SOAR-0013](https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/soar-0013).
+    case idiomatic
+}
+
 /// A structure that contains configuration options for a single execution
 /// of the generator pipeline run.
 ///
@@ -35,6 +49,14 @@ public struct Config: Sendable {
     /// Filter to apply to the OpenAPI document before generation.
     public var filter: DocumentFilter?
 
+    /// The naming strategy to use for deriving Swift identifiers from OpenAPI identifiers.
+    ///
+    /// Defaults to `defensive`.
+    public var namingStrategy: NamingStrategy
+
+    /// A map of OpenAPI identifiers to desired Swift identifiers, used instead of the naming strategy.
+    public var nameOverrides: [String: String]
+
     /// Additional pre-release features to enable.
     public var featureFlags: FeatureFlags
 
@@ -44,18 +66,26 @@ public struct Config: Sendable {
     ///   - access: The access modifier to use for generated declarations.
     ///   - additionalImports: Additional imports to add to each generated file.
     ///   - filter: Filter to apply to the OpenAPI document before generation.
+    ///   - namingStrategy: The naming strategy to use for deriving Swift identifiers from OpenAPI identifiers.
+    ///     Defaults to `defensive`.
+    ///   - nameOverrides: A map of OpenAPI identifiers to desired Swift identifiers, used instead
+    ///     of the naming strategy.
     ///   - featureFlags: Additional pre-release features to enable.
     public init(
         mode: GeneratorMode,
         access: AccessModifier,
         additionalImports: [String] = [],
         filter: DocumentFilter? = nil,
+        namingStrategy: NamingStrategy = .defensive,
+        nameOverrides: [String: String] = [:],
         featureFlags: FeatureFlags = []
     ) {
         self.mode = mode
         self.access = access
         self.additionalImports = additionalImports
         self.filter = filter
+        self.namingStrategy = namingStrategy
+        self.nameOverrides = nameOverrides
         self.featureFlags = featureFlags
     }
 }

Sources/_OpenAPIGeneratorCore/Translator/ClientTranslator/translateClientMethod.swift

@@ -145,7 +145,7 @@ extension ClientFileTranslator {
     func translateClientMethod(_ description: OperationDescription) throws -> Declaration {
 
         let operationTypeExpr = Expression.identifierType(.member(Constants.Operations.namespace))
-            .dot(description.methodName)
+            .dot(description.operationTypeName)
 
         let operationArg = FunctionArgumentDescription(label: "forOperation", expression: operationTypeExpr.dot("id"))
         let inputArg = FunctionArgumentDescription(

Sources/_OpenAPIGeneratorCore/Translator/CommonTranslations/SwiftSafeNames.swift

@@ -144,7 +144,7 @@ extension TypesFileTranslator {
                     userDescription: nil,
                     parent: typeName
                 )
-                let caseName = safeSwiftNameForOneOfMappedType(mappedType)
+                let caseName = safeSwiftNameForOneOfMappedCase(mappedType)
                 return (caseName, mappedType.rawNames, true, comment, mappedType.typeName.asUsage, [])
             }
         } else {
@@ -209,7 +209,7 @@ extension TypesFileTranslator {
         let decoder: Declaration
         if let discriminator {
             let originalName = discriminator.propertyName
-            let swiftName = context.asSwiftSafeName(originalName)
+            let swiftName = context.safeNameGenerator.swiftMemberName(for: originalName)
             codingKeysDecls = [
                 .enum(
                     accessModifier: config.access,

Sources/_OpenAPIGeneratorCore/Translator/CommonTranslations/translateAllAnyOneOf.swift

@@ -101,12 +101,12 @@ extension FileTranslator {
                 // This is unlikely to be fixed, so handling that case here.
                 // https://github.com/apple/swift-openapi-generator/issues/118
                 if isNullable && anyValue is Void {
-                    try addIfUnique(id: .string(""), caseName: context.asSwiftSafeName(""))
+                    try addIfUnique(id: .string(""), caseName: context.safeNameGenerator.swiftMemberName(for: ""))
                 } else {
                     guard let rawValue = anyValue as? String else {
                         throw GenericError(message: "Disallowed value for a string enum '\(typeName)': \(anyValue)")
                     }
-                    let caseName = context.asSwiftSafeName(rawValue)
+                    let caseName = context.safeNameGenerator.swiftMemberName(for: rawValue)
                     try addIfUnique(id: .string(rawValue), caseName: caseName)
                 }
             case .integer:

Sources/_OpenAPIGeneratorCore/Translator/CommonTranslations/translateRawEnum.swift

@@ -79,8 +79,8 @@ extension FileTranslator {
     /// component.
     /// - Parameter type: The `OneOfMappedType` for which to determine the case name.
     /// - Returns: A string representing the safe Swift name for the specified `OneOfMappedType`.
-    func safeSwiftNameForOneOfMappedType(_ type: OneOfMappedType) -> String {
-        context.asSwiftSafeName(type.rawNames[0])
+    func safeSwiftNameForOneOfMappedCase(_ type: OneOfMappedType) -> String {
+        context.safeNameGenerator.swiftMemberName(for: type.rawNames[0])
     }
 }
 

Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/DiscriminatorExtensions.swift

@@ -153,7 +153,7 @@ struct PropertyBlueprint {
 extension PropertyBlueprint {
 
     /// A name that is verified to be a valid Swift identifier.
-    var swiftSafeName: String { context.asSwiftSafeName(originalName) }
+    var swiftSafeName: String { context.safeNameGenerator.swiftMemberName(for: originalName) }
 
     /// The JSON path to the property.
     ///

Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/StructBlueprint.swift

@@ -44,18 +44,50 @@ protocol FileTranslator {
     func translateFile(parsedOpenAPI: ParsedOpenAPIRepresentation) throws -> StructuredSwiftRepresentation
 }
 
+/// A generator that allows overriding the documented name.
+struct OverridableSafeNameGenerator: SafeNameGenerator {
+
+    /// The upstream name generator for names that aren't overriden.
+    var upstream: any SafeNameGenerator
+
+    /// A set of overrides, where the key is the documented name and the value the desired identifier.
+    var overrides: [String: String]
+
+    func swiftTypeName(for documentedName: String) -> String {
+        if let override = overrides[documentedName] { return override }
+        return upstream.swiftTypeName(for: documentedName)
+    }
+
+    func swiftMemberName(for documentedName: String) -> String {
+        if let override = overrides[documentedName] { return override }
+        return upstream.swiftMemberName(for: documentedName)
+    }
+
+    func swiftContentTypeName(for contentType: ContentType) -> String {
+        upstream.swiftContentTypeName(for: contentType)
+    }
+}
+
 extension FileTranslator {
 
     /// A new context from the file translator.
-    var context: TranslatorContext { TranslatorContext(asSwiftSafeName: { $0.safeForSwiftCode }) }
+    var context: TranslatorContext {
+        let safeNameGenerator: any SafeNameGenerator
+        switch config.namingStrategy {
+        case .defensive: safeNameGenerator = .defensive
+        case .idiomatic: safeNameGenerator = .idiomatic
+        }
+        let overridingGenerator = OverridableSafeNameGenerator(
+            upstream: safeNameGenerator,
+            overrides: config.nameOverrides
+        )
+        return TranslatorContext(safeNameGenerator: overridingGenerator)
+    }
 }
 
 /// A set of configuration values for concrete file translators.
 struct TranslatorContext {
 
-    /// A closure that returns a copy of the string modified to be a valid Swift identifier.
-    ///
-    /// - Parameter string: The string to convert to be safe for Swift.
-    /// - Returns: A Swift-safe version of the input string.
-    var asSwiftSafeName: (String) -> String
+    /// A type that generates safe names for use as Swift identifiers.
+    var safeNameGenerator: any SafeNameGenerator
 }

Sources/_OpenAPIGeneratorCore/Translator/FileTranslator.swift

@@ -120,7 +120,7 @@ extension FileTranslator {
         }
         var parts: [MultipartSchemaTypedContent] = try topLevelObject.properties.compactMap {
             (key, value) -> MultipartSchemaTypedContent? in
-            let swiftSafeName = context.asSwiftSafeName(key)
+            let swiftSafeName = context.safeNameGenerator.swiftTypeName(for: key)
             let typeName = typeName.appending(
                 swiftComponent: swiftSafeName + Constants.Global.inlineTypeSuffix,
                 jsonComponent: key

Sources/_OpenAPIGeneratorCore/Translator/Multipart/MultipartContentInspector.swift

@@ -137,7 +137,7 @@ extension TypesFileTranslator {
             switch part {
             case .documentedTyped(let documentedPart):
                 let caseDecl: Declaration = .enumCase(
-                    name: context.asSwiftSafeName(documentedPart.originalName),
+                    name: context.safeNameGenerator.swiftMemberName(for: documentedPart.originalName),
                     kind: .nameWithAssociatedValues([.init(type: .init(part.wrapperTypeUsage))])
                 )
                 let decl = try translateMultipartPartContent(
@@ -404,7 +404,7 @@ extension FileTranslator {
             switch part {
             case .documentedTyped(let part):
                 let originalName = part.originalName
-                let identifier = context.asSwiftSafeName(originalName)
+                let identifier = context.safeNameGenerator.swiftMemberName(for: originalName)
                 let contentType = part.partInfo.contentType
                 let partTypeName = part.typeName
                 let schema = part.schema
@@ -613,7 +613,7 @@ extension FileTranslator {
             switch part {
             case .documentedTyped(let part):
                 let originalName = part.originalName
-                let identifier = context.asSwiftSafeName(originalName)
+                let identifier = context.safeNameGenerator.swiftMemberName(for: originalName)
                 let contentType = part.partInfo.contentType
                 let headersTypeName = part.typeName.appending(
                     swiftComponent: Constants.Operation.Output.Payload.Headers.typeName,