Generate enums for server variables

Sources/_OpenAPIGeneratorCore/Layers/StructuredSwiftRepresentation.swift

@@ -1628,9 +1628,15 @@ extension KeywordKind {
 }
 
 extension Declaration {
+    /// Returns a new deprecated variant of the declaration if the provided `description` is not `nil`.
+    func deprecate(if description: DeprecationDescription?) -> Self {
+        if let description { return .deprecated(description, self) }
+        return self
+    }
+
     /// Returns a new deprecated variant of the declaration if `shouldDeprecate` is true.
-    func deprecate(if shouldDeprecate: Bool) -> Self {
-        if shouldDeprecate { return .deprecated(.init(), self) }
+    func deprecate(if shouldDeprecate: Bool, description: @autoclosure () -> DeprecationDescription = .init()) -> Self {
+        if shouldDeprecate { return .deprecated(description(), self) }
         return self
     }
 

Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/Constants.swift

@@ -56,6 +56,19 @@ enum Constants {
 
         /// The prefix of each generated method name.
         static let propertyPrefix: String = "server"
+
+        /// The name of each generated static function.
+        static let urlStaticFunc: String = "url"
+
+        /// The prefix of the namespace that contains server specific variables.
+        static let serverNamespacePrefix: String = "Server"
+
+        /// Constants related to the OpenAPI server variable object.
+        enum Variable {
+
+            /// The types that the protocol conforms to.
+            static let conformances: [String] = [TypeName.string.fullyQualifiedSwiftName, "Sendable"]
+        }
     }
 
     /// Constants related to the configuration type, which is used by both

Sources/_OpenAPIGeneratorCore/Translator/TypesTranslator/translateServers.swift

@@ -14,47 +14,46 @@
 import OpenAPIKit
 
 extension TypesFileTranslator {
-
-    /// Returns a declaration of a server URL static method defined in
-    /// the OpenAPI document.
+    /// Returns a declaration of a server URL static function defined in
+    /// the OpenAPI document using the supplied name identifier and
+    /// variable generators.
+    ///
+    /// If the `deprecated` parameter is supplied the static function
+    /// will be generated with a name that matches the previous, now
+    /// deprecated API.
+    ///
+    /// - Important: The variable generators provided should all
+    /// be ``RawStringTranslatedServerVariable`` to ensure
+    /// the generated function matches the previous implementation, this
+    /// is **not** asserted by this translate function.
+    ///
+    /// If the `deprecated` parameter is `nil` then the function will
+    /// be generated with the identifier `url` and must be a member
+    /// of a namespace to avoid conflicts with other server URL static
+    /// functions.
+    ///
     /// - Parameters:
     ///   - index: The index of the server in the list of servers defined
     ///   in the OpenAPI document.
     ///   - server: The server URL information.
+    ///   - deprecated: A deprecation `@available` annotation to attach
+    ///   to this declaration, or `nil` if the declaration should not be deprecated.
+    ///   - variables: The generators for variables the server has defined.
     /// - Returns: A static method declaration, and a name for the variable to
     /// declare the method under.
-    func translateServer(index: Int, server: OpenAPI.Server) -> Declaration {
-        let methodName = "\(Constants.ServerURL.propertyPrefix)\(index+1)"
-        let safeVariables = server.variables.map { (key, value) in
-            (originalKey: key, swiftSafeKey: context.asSwiftSafeName(key), value: value)
-        }
-        let parameters: [ParameterDescription] = safeVariables.map { (originalKey, swiftSafeKey, value) in
-            .init(label: swiftSafeKey, type: .init(TypeName.string), defaultValue: .literal(value.default))
-        }
-        let variableInitializers: [Expression] = safeVariables.map { (originalKey, swiftSafeKey, value) in
-            let allowedValuesArg: FunctionArgumentDescription?
-            if let allowedValues = value.enum {
-                allowedValuesArg = .init(
-                    label: "allowedValues",
-                    expression: .literal(.array(allowedValues.map { .literal($0) }))
-                )
-            } else {
-                allowedValuesArg = nil
-            }
-            return .dot("init")
-                .call(
-                    [
-                        .init(label: "name", expression: .literal(originalKey)),
-                        .init(label: "value", expression: .identifierPattern(swiftSafeKey)),
-                    ] + (allowedValuesArg.flatMap { [$0] } ?? [])
-                )
-        }
-        let methodDecl = Declaration.commentable(
-            .functionComment(abstract: server.description, parameters: safeVariables.map { ($1, $2.description) }),
+    private func translateServerStaticFunction(
+        index: Int,
+        server: OpenAPI.Server,
+        deprecated: DeprecationDescription?,
+        variableGenerators variables: [any ServerVariableGenerator]
+    ) -> Declaration {
+        let name = deprecated == nil ? Constants.ServerURL.urlStaticFunc : "\(Constants.ServerURL.propertyPrefix)\(index + 1)"
+        return .commentable(
+            .functionComment(abstract: server.description, parameters: variables.map(\.functionComment)),
             .function(
                 accessModifier: config.access,
-                kind: .function(name: methodName, isStatic: true),
-                parameters: parameters,
+                kind: .function(name: name, isStatic: true),
+                parameters: variables.map(\.parameter),
                 keywords: [.throws],
                 returnType: .identifierType(TypeName.url),
                 body: [
@@ -65,14 +64,70 @@ extension TypesFileTranslator {
                                     .init(
                                         label: "validatingOpenAPIServerURL",
                                         expression: .literal(.string(server.urlTemplate.absoluteString))
-                                    ), .init(label: "variables", expression: .literal(.array(variableInitializers))),
+                                    ),
+                                    .init(
+                                        label: "variables",
+                                        expression: .literal(.array(variables.map(\.initializer)))
+                                    )
                                 ])
                         )
                     )
                 ]
+            ).deprecate(if: deprecated)
+        )
+    }
+
+    /// Returns a declaration of a server URL static function defined in
+    /// the OpenAPI document. The function is marked as deprecated
+    /// with a message informing the adopter to use the new type-safe
+    /// API.
+    /// - Parameters:
+    ///   - index: The index of the server in the list of servers defined
+    ///   in the OpenAPI document.
+    ///   - server: The server URL information.
+    ///   - pathToReplacementSymbol: The Swift path of the symbol
+    ///   which has resulted in the deprecation of this symbol.
+    /// - Returns: A static function declaration.
+    func translateServerAsDeprecated(index: Int, server: OpenAPI.Server, renamedTo pathToReplacementSymbol: String) -> Declaration {
+        let serverVariables = translateServerVariables(index: index, server: server, generateAsEnum: false)
+        return translateServerStaticFunction(index: index,
+                                             server: server,
+                                             deprecated: DeprecationDescription(renamed: pathToReplacementSymbol),
+                                             variableGenerators: serverVariables)
+    }
+
+    /// Returns a namespace (enum) declaration for a server defined in
+    /// the OpenAPI document. Within the namespace are enums to
+    /// represent any variables that also have enum values defined in the
+    /// OpenAPI document, and a single static function named 'url' which
+    /// at runtime returns the resolved server URL.
+    ///
+    /// The server's namespace is named to identify the human-friendly
+    /// index of the enum (e.g. Server1) and is present to ensure each
+    /// server definition's variables do not conflict with one another.
+    /// - Parameters:
+    ///   - index: The index of the server in the list of servers defined
+    ///   in the OpenAPI document.
+    ///   - server: The server URL information.
+    /// - Returns: A static function declaration.
+    func translateServer(index: Int, server: OpenAPI.Server) -> (pathToStaticFunction: String, decl: Declaration) {
+        let serverVariables = translateServerVariables(index: index, server: server, generateAsEnum: true)
+        let methodDecl = translateServerStaticFunction(index: index,
+                                                       server: server,
+                                                       deprecated: nil,
+                                                       variableGenerators: serverVariables)
+
+        let namespaceName = "\(Constants.ServerURL.serverNamespacePrefix)\(index + 1)"
+        let typeName = TypeName(swiftKeyPath: [Constants.ServerURL.namespace, namespaceName, Constants.ServerURL.urlStaticFunc])
+        let decl = Declaration.commentable(
+            server.description.map(Comment.doc(_:)),
+            .enum(
+                accessModifier: config.access,
+                name: namespaceName,
+                members: serverVariables.compactMap(\.declaration) + CollectionOfOne(methodDecl)
             )
         )
-        return methodDecl
+        return (pathToStaticFunction: typeName.fullyQualifiedSwiftName, decl: decl)
     }
 
     /// Returns a declaration of a namespace (enum) called "Servers" that
@@ -81,7 +136,16 @@ extension TypesFileTranslator {
     /// - Parameter servers: The servers to include in the extension.
     /// - Returns: A declaration of an enum namespace of the server URLs type.
     func translateServers(_ servers: [OpenAPI.Server]) -> Declaration {
-        let serverDecls = servers.enumerated().map(translateServer)
+        var serverDecls: [Declaration] = []
+
+        for (index, server) in servers.enumerated() {
+            let translatedServer = translateServer(index: index, server: server)
+            serverDecls.append(contentsOf: [
+                translatedServer.decl,
+                translateServerAsDeprecated(index: index, server: server, renamedTo: translatedServer.pathToStaticFunction)
+            ])
+        }
+
         return .commentable(
             .doc("Server URLs defined in the OpenAPI document."),
             .enum(accessModifier: config.access, name: Constants.ServerURL.namespace, members: serverDecls)