Open API and documentation improvements (#20)

This PR contains the work done to polish the `Open API` specification document as well as the `DocC` documentation even further, by removing unnecessary intermediate types and adding missing documentation.

Reviewed-on: #20
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

Sources/AmiiboService/Public/Clients/AmiiboLiveClient.swift

@@ -203,7 +203,7 @@ private extension AmiiboLiveClient {
                 switch output.amiibo {
                 case let .Amiibo(object):
                     return [Amiibo(object)]
-                case let .AmiiboList(list):
+                case let .case2(list):
                     return list
                         .map { Amiibo($0) }
                         .sorted { $0.identifier < $1.identifier }
@@ -247,7 +247,7 @@ private extension AmiiboLiveClient {
                 switch output.amiibo {
                 case let .AmiiboSeries(payload):
                     return [AmiiboSeries(payload.value1)]
-                case let .AmiiboSeriesList(list):
+                case let .case2(list):
                     return list
                         .map { AmiiboSeries($0.value1) }
                         .sorted { $0.key < $1.key }
@@ -289,7 +289,7 @@ private extension AmiiboLiveClient {
                 switch output.amiibo {
                 case let .AmiiboType(payload):
                     return [AmiiboType(payload.value1)]
-                case let .AmiiboTypeList(list):
+                case let .case2(list):
                     return list
                         .map { AmiiboType($0.value1) }
                         .sorted { $0.key < $1.key }
@@ -331,7 +331,7 @@ private extension AmiiboLiveClient {
                 switch output.amiibo {
                 case let .GameCharacter(payload):
                     return [GameCharacter(payload.value1)]
-                case let .GameCharacterList(list):
+                case let .case2(list):
                     return list
                         .map { GameCharacter($0.value1) }
                         .sorted { $0.key < $1.key }
@@ -373,7 +373,7 @@ private extension AmiiboLiveClient {
                 switch output.amiibo {
                 case let .GameSeries(payload):
                     return [GameSeries(payload.value1)]
-                case let .GameSeriesList(list):
+                case let .case2(list):
                     return list
                         .map { GameSeries($0.value1) }
                         .sorted { $0.key < $1.key }

Sources/AmiiboService/Public/Models/AmiiboSeries.swift

@@ -14,19 +14,19 @@
 
 /// A model that represents an amiibo series.
 public struct AmiiboSeries: KeyNameModel {
-    
-    // TODO: Remove the documentation from the properties of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
-    
+
     // MARK: Properties
 
-    /// A key.
+    /// An amiibo series key.
     public let key: String
 
-    /// A name.
+    /// An amiibo series name.
     public let name: String
     
     // MARK: Initializers
     
+    /// Initializes this model from a given payload.
+    /// - Parameter payload: A payload that contains the values for the model.
     init(_ payload: Components.Schemas.Tuple) {
         self.key = payload.key
         self.name = payload.name

Sources/AmiiboService/Public/Models/AmiiboType.swift

@@ -15,18 +15,18 @@
 /// A model that represents an amiibo type.
 public struct AmiiboType: KeyNameModel {
 
-    // TODO: Remove the documentation from the properties of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
-
     // MARK: Properties
 
-    /// A key.
+    /// An amiibo type key.
     public let key: String
 
-    /// A name.
+    /// An amiibo type name.
     public let name: String
     
     // MARK: Initializers
     
+    /// Initializes this model from a given payload.
+    /// - Parameter payload: A payload that contains the values for the model.
     init(_ payload: Components.Schemas.Tuple) {
         self.key = payload.key
         self.name = payload.name

Sources/AmiiboService/Public/Models/GameCharacter.swift

@@ -15,18 +15,18 @@
 /// A model that represents a game character.
 public struct GameCharacter: KeyNameModel {
 
-    // TODO: Remove the documentation from the properties of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
-
     // MARK: Properties
 
-    /// A key.
+    /// A game character key.
     public let key: String
 
-    /// A name.
+    /// A game character  name.
     public let name: String
     
     // MARK: Initializers
-    
+
+    /// Initializes this model from a given payload.
+    /// - Parameter payload: A payload that contains the values for the model.
     init(_ payload: Components.Schemas.Tuple) {
         self.key = payload.key
         self.name = payload.name

Sources/AmiiboService/Public/Models/GameSeries.swift

@@ -15,18 +15,18 @@
 /// A model that represents a game series.
 public struct GameSeries: KeyNameModel {
 
-    // TODO: Remove the documentation from the properties of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
-
     // MARK: Properties
 
-    /// A key.
+    /// A game series key.
     public let key: String
 
-    /// A name.
+    /// A game series name.
     public let name: String
     
     // MARK: Initializers
     
+    /// Initializes this model from a given payload.
+    /// - Parameter payload: A payload that contains the values for the model.
     init(_ payload: Components.Schemas.Tuple) {
         self.key = payload.key
         self.name = payload.name