Add Tag support for the kind field

Author: mattpolzin

Sources/OpenAPIKit/Tag.swift

@@ -19,6 +19,12 @@ extension OpenAPI {
         public let externalDocs: ExternalDocumentation?
         /// The tag this tag is nested under.
         public let parent: String?
+        /// A machine-readable string to categorize what sort of tag this is.
+        /// Any string value can be used, but some common options are provided
+        /// on OpenAPIKit's `Tag.Kind` type as static properties and more can
+        /// be found in the public registry:
+        /// https://spec.openapis.org/registry/tag-kind
+        public let kind: Kind?
 
         /// Dictionary of vendor extensions.
         ///
@@ -35,25 +41,59 @@ extension OpenAPI {
             description: String? = nil,
             externalDocs: ExternalDocumentation? = nil,
             parent: String? = nil,
+            kind: Kind? = nil,
             vendorExtensions: [String: AnyCodable] = [:]
         ) {
             self.name = name
             self.summary = summary
             self.description = description
             self.externalDocs = externalDocs
             self.parent = parent
+            self.kind = kind
             self.vendorExtensions = vendorExtensions
 
             self.conditionalWarnings = [
                 // If summary is non-nil, the document must be OAS version 3.2.0 or greater
                 nonNilVersionWarning(fieldName: "summary", value: summary, minimumVersion: .v3_2_0),
                 // If parent is non-nil, the document must be OAS version 3.2.0 or greater
-                nonNilVersionWarning(fieldName: "parent", value: parent, minimumVersion: .v3_2_0)
+                nonNilVersionWarning(fieldName: "parent", value: parent, minimumVersion: .v3_2_0),
+                // If kind is non-nil, the document must be OAS version 3.2.0 or greater
+                nonNilVersionWarning(fieldName: "kind", value: kind, minimumVersion: .v3_2_0)
             ].compactMap { $0 }
         }
     }
 }
 
+extension OpenAPI.Tag {
+    public struct Kind : ExpressibleByStringLiteral, Codable, Equatable, Sendable {
+        public let rawValue: String
+
+        public init(stringLiteral: String) {
+            self.rawValue = stringLiteral
+        }
+
+        public init(from decoder: Decoder) throws {
+            let container = try decoder.singleValueContainer()
+            self.rawValue = try container.decode(String.self)
+        }
+
+      public func encode(to encoder: Encoder) throws {
+          var container = encoder.singleValueContainer()
+
+          try container.encode(rawValue)
+      }
+    }
+}
+
+extension OpenAPI.Tag.Kind {
+    /// See https://spec.openapis.org/registry/tag-kind/audience.html
+    public static let audience: OpenAPI.Tag.Kind = "audience"
+    /// See https://spec.openapis.org/registry/tag-kind/badge.html
+    public static let badge: OpenAPI.Tag.Kind = "badge"
+    /// See https://spec.openapis.org/registry/tag-kind/nav.html
+    public static let nav: OpenAPI.Tag.Kind = "nav"
+}
+
 fileprivate func nonNilVersionWarning<Subject>(fieldName: String, value: Subject?, minimumVersion: OpenAPI.Document.Version) -> (any Condition, OpenAPI.Warning)? {
     value.map { _ in
         OpenAPI.Document.ConditionalWarnings.version(
@@ -70,6 +110,7 @@ extension OpenAPI.Tag: Equatable {
           && lhs.description == rhs.description
           && lhs.externalDocs == rhs.externalDocs
           && lhs.parent == rhs.parent
+          && lhs.kind == rhs.kind
           && lhs.vendorExtensions == rhs.vendorExtensions
     }
 }
@@ -91,6 +132,7 @@ extension OpenAPI.Tag : OpenAPISummarizable {
             description: description,
             externalDocs: externalDocs,
             parent: parent,
+            kind: kind,
             vendorExtensions: vendorExtensions
         )
     }
@@ -103,6 +145,7 @@ extension OpenAPI.Tag : OpenAPISummarizable {
             description: description,
             externalDocs: externalDocs,
             parent: parent,
+            kind: kind,
             vendorExtensions: vendorExtensions
         )
     }
@@ -124,6 +167,8 @@ extension OpenAPI.Tag: Encodable {
 
         try container.encodeIfPresent(parent, forKey: .parent)
 
+        try container.encodeIfPresent(kind, forKey: .kind)
+
         if VendorExtensionsConfiguration.isEnabled(for: encoder) {
             try encodeExtensions(to: &container)
         }
@@ -144,13 +189,17 @@ extension OpenAPI.Tag: Decodable {
 
         parent = try container.decodeIfPresent(String.self, forKey: .parent)
 
+        kind = try container.decodeIfPresent(Kind.self, forKey: .kind)
+
         vendorExtensions = try Self.extensions(from: decoder)
 
         conditionalWarnings = [
             // If summary is non-nil, the document must be OAS version 3.2.0 or greater
             nonNilVersionWarning(fieldName: "summary", value: summary, minimumVersion: .v3_2_0),
             // If parent is non-nil, the document must be OAS version 3.2.0 or greater
-            nonNilVersionWarning(fieldName: "parent", value: parent, minimumVersion: .v3_2_0)
+            nonNilVersionWarning(fieldName: "parent", value: parent, minimumVersion: .v3_2_0),
+            // If kind is non-nil, the document must be OAS version 3.2.0 or greater
+            nonNilVersionWarning(fieldName: "kind", value: kind, minimumVersion: .v3_2_0)
         ].compactMap { $0 }
     }
 }
@@ -162,6 +211,7 @@ extension OpenAPI.Tag {
         case description
         case externalDocs
         case parent
+        case kind
         case extended(String)
 
         static var allBuiltinKeys: [CodingKeys] {
@@ -170,7 +220,8 @@ extension OpenAPI.Tag {
                 .summary,
                 .description,
                 .externalDocs,
-                .parent
+                .parent,
+                .kind
             ]
         }
 
@@ -190,6 +241,8 @@ extension OpenAPI.Tag {
                 self = .externalDocs
             case "parent":
                 self = .parent
+            case "kind":
+                self = .kind
             default:
                 self = .extendedKey(for: stringValue)
             }
@@ -207,6 +260,8 @@ extension OpenAPI.Tag {
                 return "externalDocs"
             case .parent:
                 return "parent"
+            case .kind:
+                return "kind"
             case .extended(let key):
                 return key
             }

Tests/OpenAPIKitTests/TagTests.swift

@@ -45,6 +45,12 @@ final class TagTests: XCTestCase {
             parent: "otherTag"
         )
         XCTAssertEqual(t5.parent, "otherTag")
+
+        let t6 = OpenAPI.Tag(
+            name: "hello",
+            kind: .nav
+        )
+        XCTAssertEqual(t6.kind, .nav)
     }
 }
 
@@ -177,6 +183,39 @@ extension TagTests {
         XCTAssertEqual(tag.conditionalWarnings.count, 1)
     }
 
+    func test_nameAndKind_encode() throws {
+        let tag = OpenAPI.Tag(
+            name: "hello",
+            kind: .badge
+        )
+        let encodedTag = try orderUnstableTestStringFromEncoding(of: tag)
+
+        assertJSONEquivalent(
+            encodedTag,
+            """
+            {
+              "kind" : "badge",
+              "name" : "hello"
+            }
+            """
+        )
+    }
+
+    func test_nameAndKind_decode() throws {
+        let tagData =
+        """
+        {
+            "name": "hello",
+            "kind": "audience"
+        }
+        """.data(using: .utf8)!
+
+        let tag = try orderUnstableDecode(OpenAPI.Tag.self, from: tagData)
+
+        XCTAssertEqual(tag, OpenAPI.Tag(name: "hello", kind: .audience))
+        XCTAssertEqual(tag.conditionalWarnings.count, 1)
+    }
+
     func test_allFields_encode() throws {
         let tag = OpenAPI.Tag(
             name: "hello",
@@ -186,6 +225,7 @@ extension TagTests {
                 url: URL(string: "http://google.com")!
             ),
             parent: "otherTag",
+            kind: "mytag",
             vendorExtensions: ["x-specialFeature": false]
         )
         let encodedTag = try orderUnstableTestStringFromEncoding(of: tag)
@@ -198,6 +238,7 @@ extension TagTests {
               "externalDocs" : {
                 "url" : "http:\\/\\/google.com"
               },
+              "kind" : "mytag",
               "name" : "hello",
               "parent" : "otherTag",
               "summary" : "sum",
@@ -218,6 +259,7 @@ extension TagTests {
                 "url": "http://google.com"
             },
             "parent": "otherTag",
+            "kind": "mytag",
             "x-specialFeature" : false
         }
         """.data(using: .utf8)!
@@ -232,9 +274,10 @@ extension TagTests {
                 description: "world",
                 externalDocs: .init(url: URL(string: "http://google.com")!),
                 parent: "otherTag",
+                kind: "mytag",
                 vendorExtensions: ["x-specialFeature": false]
             )
         )
-        XCTAssertEqual(tag.conditionalWarnings.count, 2)
+        XCTAssertEqual(tag.conditionalWarnings.count, 3)
     }
 }