Fix the OpenAPI spec for LinkableEntities (#423)

The OpenAPI spec for linkable entities has fallen out of date since
we’ve updated the file to support language variants. This brings
the file up-to-date.

I verified the spec against DocC output using an OpenAPI schema
validator and it now successfully passes.

Resolves rdar://102342486

Author: ethan-kusters

Sources/SwiftDocC/Model/SourceLanguage.swift

@@ -149,4 +149,31 @@ public struct SourceLanguage: Hashable, Codable {
 
     /// The list of programming languages that are known to DocC.
     public static var knownLanguages: [SourceLanguage] = [.swift, .objectiveC, .javaScript, .data, .metal]
+    
+    enum CodingKeys: CodingKey {
+        case name
+        case id
+        case idAliases
+        case linkDisambiguationID
+    }
+    
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: SourceLanguage.CodingKeys.self)
+        
+        let name = try container.decode(String.self, forKey: SourceLanguage.CodingKeys.name)
+        let id = try container.decode(String.self, forKey: SourceLanguage.CodingKeys.id)
+        let idAliases = try container.decodeIfPresent([String].self, forKey: SourceLanguage.CodingKeys.idAliases) ?? []
+        let linkDisambiguationID = try container.decodeIfPresent(String.self, forKey: SourceLanguage.CodingKeys.linkDisambiguationID)
+        
+        self.init(name: name, id: id, idAliases: idAliases, linkDisambiguationID: linkDisambiguationID)
+    }
+    
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: SourceLanguage.CodingKeys.self)
+        
+        try container.encode(self.name, forKey: SourceLanguage.CodingKeys.name)
+        try container.encode(self.id, forKey: SourceLanguage.CodingKeys.id)
+        try container.encodeIfNotEmpty(self.idAliases, forKey: SourceLanguage.CodingKeys.idAliases)
+        try container.encode(self.linkDisambiguationID, forKey: SourceLanguage.CodingKeys.linkDisambiguationID)
+    }
 }

Sources/SwiftDocC/SwiftDocC.docc/Resources/LinkableEntities.json

@@ -16,6 +16,7 @@
             },
             "LinkDestinationSummary": {
                 "type": "object",
+                "additionalProperties": false,
                 "required": [
                     "kind",
                     "language",
@@ -67,7 +68,7 @@
                     "usr": {
                         "type": "string"
                     },
-                    "declarationFragments": {
+                    "fragments": {
                         "type": "array",
                         "items": {
                             "$ref": "#/components/schemas/DeclarationToken"
@@ -99,6 +100,15 @@
                     },
                     "id": {
                         "type": "string"
+                    },
+                    "idAliases": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "linkDisambiguationID": {
+                        "type": "string"
                     }
                 }
             },
@@ -122,6 +132,7 @@
             },
             "LinkDestinationSummaryVariant": {
                 "type": "object",
+                "additionalProperties": false,
                 "required": [
                     "traits"
                 ],
@@ -133,37 +144,45 @@
                         }
                     },
                     "kind": {
-                        "type": "string"
+                        "type": "string",
+                        "nullable": true
                     },
                     "language": {
-                        "type": "string"
+                        "$ref": "#/components/schemas/SourceLanguage",
+                        "nullable": true
                     },
                     "path": {
-                        "type": "string"
+                        "type": "string",
+                        "nullable": true
                     },
                     "title": {
-                        "type": "string"
+                        "type": "string",
+                        "nullable": true
                     },
                     "abstract": {
                         "type": "array",
                         "items": {
                             "$ref": "#/components/schemas/RenderInlineContent"
-                        }
+                        },
+                        "nullable": true
                     },
                     "usr": {
-                        "type": "string"
+                        "type": "string",
+                        "nullable": true
                     },
-                    "declarationFragments": {
+                    "fragments": {
                         "type": "array",
                         "items": {
                             "$ref": "#/components/schemas/DeclarationToken"
-                        }
+                        },
+                        "nullable": true
                     },
                     "taskGroups": {
                         "type": "array",
                         "items": {
                             "$ref": "#/components/schemas/TaskGroup"
-                        }
+                        },
+                        "nullable": true
                     }
                 }
             },