Merge pull request #473 from mattpolzin/feature/448/server-object-name

OAS 3.2.0 Server Object changes

Author: mattpolzin

Sources/OpenAPIKit/Server.swift

@@ -13,11 +13,13 @@ extension OpenAPI {
     ///
     /// See [OpenAPI Server Object](https://spec.openapis.org/oas/v3.1.1.html#server-object).
     ///
-    public struct Server: Equatable, CodableVendorExtendable, Sendable {
+    public struct Server: HasConditionalWarnings, CodableVendorExtendable, Sendable {
         /// OpenAPI Server URLs can have variable placeholders in them.
         /// The `urlTemplate` can be asked for a well-formed Foundation
         /// `URL` if all variables in it have been replaced by constant values.
         public let urlTemplate: URLTemplate
+        /// An optional unique string to refer to the host designated by the URL.
+        public let name: String?
         public let description: String?
         /// A map from the names of variables found in the `urlTemplate` to
         /// descriptions, allowed values, and defaults.
@@ -30,36 +32,68 @@ extension OpenAPI {
         /// where the values are anything codable.
         public var vendorExtensions: [String: AnyCodable]
 
+        public let conditionalWarnings: [(any Condition, OpenAPI.Warning)]
+
         /// Create an OpenAPI Server Object.
         public init(
             url: URL,
+            name: String? = nil,
             description: String? = nil,
             variables: OrderedDictionary<String, Variable> = [:],
             vendorExtensions: [String: AnyCodable] = [:]
         ) {
             self.urlTemplate = URLTemplate(url: url)
+            self.name = name
             self.description = description
             self.variables = variables
             self.vendorExtensions = vendorExtensions
+
+            self.conditionalWarnings = [
+                nonNilVersionWarning(fieldName: "name", value: name, minimumVersion: .v3_2_0)
+            ].compactMap { $0 }
         }
 
         /// Create an OpenAPI Server Object with a URL containing
         /// variables that can change depending on the context in
         /// which the API is invoked,
         public init(
             urlTemplate: URLTemplate,
+            name: String? = nil,
             description: String? = nil,
             variables: OrderedDictionary<String, Variable> = [:],
             vendorExtensions: [String: AnyCodable] = [:]
         ) {
             self.urlTemplate = urlTemplate
+            self.name = name
             self.description = description
             self.variables = variables
             self.vendorExtensions = vendorExtensions
+
+            self.conditionalWarnings = [
+                nonNilVersionWarning(fieldName: "name", value: name, minimumVersion: .v3_2_0)
+            ].compactMap { $0 }
         }
     }
 }
 
+extension OpenAPI.Server: Equatable {
+    public static func == (lhs: Self, rhs: Self) -> Bool {
+        lhs.urlTemplate == rhs.urlTemplate
+        && lhs.description == rhs.description
+        && lhs.variables == rhs.variables
+        && lhs.vendorExtensions == rhs.vendorExtensions
+    }
+}
+
+fileprivate func nonNilVersionWarning<Subject>(fieldName: String, value: Subject?, minimumVersion: OpenAPI.Document.Version) -> (any Condition, OpenAPI.Warning)? {
+    value.map { _ in
+        OpenAPI.Document.ConditionalWarnings.version(
+            lessThan: minimumVersion,
+            doesNotSupport: "The Server \(fieldName) field"
+        )
+    }
+}
+
 extension OpenAPI.Server {
     /// OpenAPI Spec "Server Variable Object"
     ///
@@ -112,6 +146,7 @@ extension OpenAPI.Server: Encodable {
 
         try container.encode(urlTemplate, forKey: .url)
 
+        try container.encodeIfPresent(name, forKey: .name)
         try container.encodeIfPresent(description, forKey: .description)
 
         if variables.count > 0 {
@@ -129,16 +164,22 @@ extension OpenAPI.Server: Decodable {
         let container = try decoder.container(keyedBy: CodingKeys.self)
 
         urlTemplate = try container.decode(URLTemplate.self, forKey: .url)
+        name = try container.decodeIfPresent(String.self, forKey: .name)
         description = try container.decodeIfPresent(String.self, forKey: .description)
         variables = try container.decodeIfPresent(OrderedDictionary<String, Variable>.self, forKey: .variables) ?? [:]
 
         vendorExtensions = try Self.extensions(from: decoder)
+
+        conditionalWarnings = [
+            nonNilVersionWarning(fieldName: "name", value: name, minimumVersion: .v3_2_0)
+        ].compactMap { $0 }
     }
 }
 
 extension OpenAPI.Server {
     internal enum CodingKeys: ExtendableCodingKey {
         case url
+        case name
         case description
         case variables
 
@@ -147,6 +188,7 @@ extension OpenAPI.Server {
         static var allBuiltinKeys: [CodingKeys] {
             return [
                 .url,
+                .name,
                 .description,
                 .variables
             ]
@@ -160,6 +202,8 @@ extension OpenAPI.Server {
             switch stringValue {
             case "url":
                 self = .url
+            case "name":
+                self = .name
             case "description":
                 self = .description
             case "variables":
@@ -173,6 +217,8 @@ extension OpenAPI.Server {
             switch self {
             case .url:
                 return "url"
+            case .name:
+                return "name"
             case .description:
                 return "description"
             case .variables:

Tests/OpenAPIKitTests/ServerTests.swift

@@ -48,6 +48,21 @@ class ServerTests: XCTestCase {
         XCTAssertEqual(s2.urlTemplate, URLTemplate(rawValue: "https://hello.com")!)
         XCTAssertEqual(s2.description, "hello world")
         XCTAssertEqual(s2.variables, ["hello": variable])
+        XCTAssertEqual(s2.conditionalWarnings.count, 0)
+
+        let s3 = Server(
+            url: URL(string: "https://hello.com")!,
+            name: "name",
+            description: "hello world",
+            variables: [
+                "hello": variable
+            ]
+        )
+
+        XCTAssertEqual(s3.urlTemplate, URLTemplate(rawValue: "https://hello.com")!)
+        XCTAssertEqual(s3.description, "hello world")
+        XCTAssertEqual(s3.variables, ["hello": variable])
+        XCTAssertEqual(s3.conditionalWarnings.count, 1)
     }
 }
 
@@ -157,22 +172,25 @@ extension ServerTests {
 
         let serverDecoded = try orderUnstableDecode(Server.self, from: serverData)
 
+        let expectedServer = Server(
+            url: URL(string: "https://hello.com")!,
+            description: "hello world",
+            variables: [
+                "hello": .init(
+                    enum: ["hello"],
+                    default: "hello",
+                    description: "hello again",
+                    vendorExtensions: [ "x-otherThing": 1234 ]
+                )
+            ],
+            vendorExtensions: ["x-specialFeature": .init(["hello", "world"])]
+        )
+
         XCTAssertEqual(
             serverDecoded,
-            Server(
-                url: URL(string: "https://hello.com")!,
-                description: "hello world",
-                variables: [
-                    "hello": .init(
-                        enum: ["hello"],
-                        default: "hello",
-                        description: "hello again",
-                        vendorExtensions: [ "x-otherThing": 1234 ]
-                    )
-                ],
-                vendorExtensions: ["x-specialFeature": .init(["hello", "world"])]
-            )
+            expectedServer
         )
+        XCTAssertEqual(expectedServer.conditionalWarnings.count, 0)
     }
 
     func test_maximalServer_encode() throws {
@@ -215,4 +233,93 @@ extension ServerTests {
             """
         )
     }
+
+    func test_maximalServerPlusName_decode() throws {
+        let serverData =
+        """
+        {
+            "url": "https://hello.com",
+            "name": "name",
+            "description": "hello world",
+            "variables": {
+                "hello": {
+                    "enum": ["hello"],
+                    "default": "hello",
+                    "description": "hello again",
+                    "x-otherThing": 1234
+                }
+            },
+            "x-specialFeature": [
+                "hello",
+                "world"
+            ]
+        }
+        """.data(using: .utf8)!
+
+        let serverDecoded = try orderUnstableDecode(Server.self, from: serverData)
+
+        let expectedServer = Server(
+            url: URL(string: "https://hello.com")!,
+            name: "name",
+            description: "hello world",
+            variables: [
+                "hello": .init(
+                    enum: ["hello"],
+                    default: "hello",
+                    description: "hello again",
+                    vendorExtensions: [ "x-otherThing": 1234 ]
+                )
+            ],
+            vendorExtensions: ["x-specialFeature": .init(["hello", "world"])]
+        )
+
+        XCTAssertEqual(
+            serverDecoded,
+            expectedServer
+        )
+        XCTAssertEqual(expectedServer.conditionalWarnings.count, 1)
+    }
+
+    func test_maximalServerPlusName_encode() throws {
+        let server = Server(
+            url: URL(string: "https://hello.com")!,
+            name: "name",
+            description: "hello world",
+            variables: [
+                "hello": .init(
+                    enum: ["hello"],
+                    default: "hello",
+                    description: "hello again",
+                    vendorExtensions: [ "x-otherThing": 1234 ]
+                )
+            ],
+            vendorExtensions: ["x-specialFeature": .init(["hello", "world"])]
+        )
+        let encodedServer = try orderUnstableTestStringFromEncoding(of: server)
+
+        assertJSONEquivalent(
+            encodedServer,
+            """
+            {
+              "description" : "hello world",
+              "name" : "name",
+              "url" : "https:\\/\\/hello.com",
+              "variables" : {
+                "hello" : {
+                  "default" : "hello",
+                  "description" : "hello again",
+                  "enum" : [
+                    "hello"
+                  ],
+                  "x-otherThing" : 1234
+                }
+              },
+              "x-specialFeature" : [
+                "hello",
+                "world"
+              ]
+            }
+            """
+        )
+    }
 }