rock-n-code/amiibo-service
1
0
Fork 0
Code Issues Pull Requests Actions Releases 15 Activity

Patched (temporarily) the DocC documentation (#8)

Browse Source 
This PR contains the work done to:
* Documented the public properties, initializers, and/or functions of those types conforming to the `APIClient`, `KeyNameFilter`, and `KeyNameModel` protocols, to fix the issue that the protocol documentations cannot be inherited;
* Moved the `AmiiboService` DocC documentation catalog inside the library target;
* Amended the folder structure of the library and test targets;
* Fixed further documentation issues encountered while revising the written documentation;
* Added the `lib-test` task in the `Makefile` file;
* Improved the naming for the existing tasks in the `Makefile` file.

Reviewed-on: #8
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
This commit was merged in pull request #8.
This commit is contained in:
Javier Cicchelli
2025-09-10 19:47:45 +00:00
committed by Javier Cicchelli
parent b39fd8533b
commit 0af0e3056d
147 changed files with 290 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/AmiiboService/Public/Clients/AmiiboLiveClient.swift
+326
View File
@@ -0,0 +1,326 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
import Foundation
import OpenAPIRuntime
import OpenAPIURLSession
/// A type that implements a live client to the online service.
public struct AmiiboLiveClient {
// MARK: Properties
/// A client generated by the `OpenAPIRuntime` library.
private let client: Client
// MARK: Initializers
/// Initializes this client.
public init() {
self.client = .init(
// The force unwrapping implemented below assumes that the server definition from the OpenAPI specification is correct.
serverURL: try! Servers.Server1.url(),
configuration: .init(dateTranscoder: ISOTimestampTranscoder()),
transport: URLSessionTransport()
)
}
}
// MARK: - APIClient
// TODO: Remove the documentation from the functions inside the following extension as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
extension AmiiboLiveClient: APIClient {
// MARK: Functions
/// Gets a list of amiibo items based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered amiibo items.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getAmiibos(
by filter: AmiiboFilter
) async throws(AmiiboServiceError) -> [Amiibo] {
let response: Operations.getAmiibos.Output
do {
response = try await client.getAmiibos(
.init(query: .init(
amiiboSeries: filter.series,
character: filter.gameCharacter,
gameseries: filter.gameSeries,
id: filter.identifier,
name: filter.name,
showgames: filter.showGames,
showusage: filter.showUsage,
_type: filter.type
))
)
} catch let error as ClientError {
if error.underlyingError is DecodingError {
throw AmiiboServiceError.decoding
} else {
throw AmiiboServiceError.unknown
}
} catch {
throw AmiiboServiceError.unknown
}
switch response {
case let .ok(ok):
switch ok.body {
case let .json(output):
return map(output)
}
case .badRequest:
throw AmiiboServiceError.badRequest
case let .undocumented(statusCode, _):
throw AmiiboServiceError.undocumented(statusCode)
}
}
/// Gets a list of amiibo series based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered amiibo series.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getAmiiboSeries(
by filter: AmiiboSeriesFilter
) async throws(AmiiboServiceError) -> [AmiiboSeries] {
let response: Operations.getAmiiboSeries.Output
do {
response = try await client.getAmiiboSeries(
.init(query: .init(
key: filter.key,
name: filter.name
))
)
} catch {
throw AmiiboServiceError.unknown
}
switch response {
case let .ok(ok):
switch ok.body {
case let .json(output):
return map(output, as: AmiiboSeries.self)
}
case .badRequest:
throw AmiiboServiceError.badRequest
case .internalServerError:
throw AmiiboServiceError.notAvailable
case .notFound:
throw AmiiboServiceError.notFound
case let .undocumented(statusCode, _):
throw AmiiboServiceError.undocumented(statusCode)
}
}
/// Gets a list of amiibo types based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered amiibo types.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getAmiiboTypes(
by filter: AmiiboTypeFilter
) async throws(AmiiboServiceError) -> [AmiiboType] {
let response: Operations.getAmiiboTypes.Output
do {
response = try await client.getAmiiboTypes(
.init(query: .init(
key: filter.key,
name: filter.name
))
)
} catch {
throw AmiiboServiceError.unknown
}
switch response {
case let .ok(ok):
switch ok.body {
case let .json(output):
return map(output, as: AmiiboType.self)
}
case .badRequest:
throw AmiiboServiceError.badRequest
case .internalServerError:
throw AmiiboServiceError.notAvailable
case .notFound:
throw AmiiboServiceError.notFound
case let .undocumented(statusCode, _):
throw AmiiboServiceError.undocumented(statusCode)
}
}
/// Gets a list of game characters based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered game characters.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getGameCharacters(
by filter: GameCharacterFilter
) async throws(AmiiboServiceError) -> [GameCharacter] {
let response: Operations.getGameCharacters.Output
do {
response = try await client.getGameCharacters(
.init(query: .init(
key: filter.key,
name: filter.name
))
)
} catch {
throw AmiiboServiceError.unknown
}
switch response {
case let .ok(ok):
switch ok.body {
case let .json(output):
return map(output, as: GameCharacter.self)
}
case .badRequest:
throw AmiiboServiceError.badRequest
case .internalServerError:
throw AmiiboServiceError.notAvailable
case .notFound:
throw AmiiboServiceError.notFound
case let .undocumented(statusCode, _):
throw AmiiboServiceError.undocumented(statusCode)
}
}
/// Gets a list of game series based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered game series.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getGameSeries(
by filter: GameSeriesFilter
) async throws(AmiiboServiceError) -> [GameSeries] {
let response: Operations.getGameSeries.Output
do {
response = try await client.getGameSeries(
.init(query: .init(
key: filter.key,
name: filter.name
))
)
} catch {
throw AmiiboServiceError.unknown
}
switch response {
case let .ok(ok):
switch ok.body {
case let .json(output):
return map(output, as: GameSeries.self)
}
case .badRequest:
throw AmiiboServiceError.badRequest
case .internalServerError:
throw AmiiboServiceError.notAvailable
case .notFound:
throw AmiiboServiceError.notFound
case let .undocumented(statusCode, _):
throw AmiiboServiceError.undocumented(statusCode)
}
}
/// Gets the date when the data was last updated.
/// - Returns: A last updated date.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getLastUpdated() async throws(AmiiboServiceError) -> Date {
let response: Operations.getLastUpdated.Output
do {
response = try await client.getLastUpdated()
} catch {
throw AmiiboServiceError.unknown
}
switch response {
case let .ok(ok):
switch ok.body {
case let .json(output):
return output.lastUpdated
}
case let .undocumented(statusCode, _):
throw AmiiboServiceError.undocumented(statusCode)
}
}
}
// MARK: - Helpers
private extension AmiiboLiveClient {
// MARK: Functions
/// Retrieves a list of amiibo items from a wrapper container.
/// - Parameter wrapper: A wrapper container that either has an object or a list of items.
/// - Returns: A list of amiibo items, sorted by identifiers.
func map(
_ wrapper: Components.Schemas.AmiiboWrapper
) -> [Amiibo] {
switch wrapper.amiibo {
case let .Amiibo(object):
return [.init(object)]
case let .AmiiboList(list):
return list
.map { .init($0) }
.sorted { $0.identifier < $1.identifier }
}
}
/// Retrieves a list of items that conforms to the `KeyNameModel` protocol from a wrapper container.
/// - Parameters:
/// - wrapper: A wrapper container that either has an object or a list of items.
/// - as: a model type that conforms to the `KeyNameModel` protocol.
/// - Returns: A list of items that conforms to the `KeyNameModel` protocol, sorted by keys.
func map<Model: KeyNameModel>(
_ wrapper: Components.Schemas.TupleWrapper,
as: Model.Type
) -> [Model] {
switch wrapper.amiibo {
case let .Tuple(payload):
return [.init(payload)]
case let .TupleList(list):
return list
.map { .init($0) }
.sorted { $0.key < $1.key }
}
}
}
Sources/AmiiboService/Public/Clients/AmiiboMockClient.swift
+179
View File
@@ -0,0 +1,179 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
import Foundation
/// A type that implements a mock client, for testing purposes.
public struct AmiiboMockClient {
// MARK: Properties
/// A list of amiibo items to return, if any.
private let amiibos: [Amiibo]?
/// A list of amiibo series to return, if any.
private let amiiboSeries: [AmiiboSeries]?
/// A list of amiibo types to return, if any.
private let amiiboTypes: [AmiiboType]?
/// An error to throw, if any.
private let error: AmiiboServiceError?
/// A list of game characters to return, if any.
private let gameCharacters: [GameCharacter]?
/// A list of game series to return, if any.
private let gameSeries: [GameSeries]?
/// A last updated date to return, if any.
private let lastUpdated: Date?
// MARK: Initializers
/// Initializes this client.
/// - Parameters:
/// - amiibos: A list of amiibo items to return, if any.
/// - amiiboSeries: A list of amiibo series to return, if any.
/// - amiiboTypes: A list of amiibo types to return, if any.
/// - gameCharacters: A list of game characters to return, if any.
/// - gameSeries: A list of game series to return, if any.
/// - lastUpdated: A last updated date to return, if any.
/// - error: An error to throw, if any.
public init(
amiibos: [Amiibo]? = nil,
amiiboSeries: [AmiiboSeries]? = nil,
amiiboTypes: [AmiiboType]? = nil,
gameCharacters: [GameCharacter]? = nil,
gameSeries: [GameSeries]? = nil,
lastUpdated: Date? = nil,
error: AmiiboServiceError? = nil
) {
self.amiibos = amiibos
self.amiiboSeries = amiiboSeries
self.amiiboTypes = amiiboTypes
self.error = error
self.gameCharacters = gameCharacters
self.gameSeries = gameSeries
self.lastUpdated = lastUpdated
}
}
// MARK: - APIClient
// TODO: Remove the documentation from the functions inside the following extension as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
extension AmiiboMockClient: APIClient {
// MARK: Functions
/// Gets a list of amiibo items based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered amiibo items.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getAmiibos(by filter: AmiiboFilter) async throws(AmiiboServiceError) -> [Amiibo] {
try throwErrorIfExists()
guard let amiibos else {
throw AmiiboServiceError.notFound
}
return amiibos
}
/// Gets a list of amiibo series based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered amiibo series.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getAmiiboSeries(by filter: AmiiboSeriesFilter) async throws(AmiiboServiceError) -> [AmiiboSeries] {
try throwErrorIfExists()
guard let amiiboSeries else {
throw AmiiboServiceError.notFound
}
return amiiboSeries
}
/// Gets a list of amiibo types based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered amiibo types.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getAmiiboTypes(by filter: AmiiboTypeFilter) async throws(AmiiboServiceError) -> [AmiiboType] {
try throwErrorIfExists()
guard let amiiboTypes else {
throw AmiiboServiceError.notFound
}
return amiiboTypes
}
/// Gets a list of game characters based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered game characters.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getGameCharacters(by filter: GameCharacterFilter) async throws(AmiiboServiceError) -> [GameCharacter] {
try throwErrorIfExists()
guard let gameCharacters else {
throw AmiiboServiceError.notFound
}
return gameCharacters
}
/// Gets a list of game series based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered game series.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getGameSeries(by filter: GameSeriesFilter) async throws(AmiiboServiceError) -> [GameSeries] {
try throwErrorIfExists()
guard let gameSeries else {
throw AmiiboServiceError.notFound
}
return gameSeries
}
/// Gets the date when the data was last updated.
/// - Returns: A last updated date.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getLastUpdated() async throws(AmiiboServiceError) -> Date {
try throwErrorIfExists()
guard let lastUpdated else {
throw AmiiboServiceError.notFound
}
return lastUpdated
}
}
// MARK: - Helpers
private extension AmiiboMockClient {
// MARK: Functions
/// Throws an error if it has been provided,
/// - Throws: An ``AmiiboServiceError`` error in case an error has been provided.
func throwErrorIfExists() throws(AmiiboServiceError) {
if let error {
throw error
}
}
}
Sources/AmiiboService/Public/Enumerations/AmiiboClient.swift
+21
View File
@@ -0,0 +1,21 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// A representation of the types of client that a ``AmiiboService`` service can utilize.
///
/// > important: This enumeration has been defined as a way to avoid exposing the `APIClient` protocol outside the boundaries of this library.
public enum AmiiboClient {
/// A live Amiibo client to interact with the online service.
case live(AmiiboLiveClient = .init())
///A mock Amiibo client, for testing purposes.
case mock(AmiiboMockClient)
}
Sources/AmiiboService/Public/Errors/AmiiboServiceError.swift
+31
View File
@@ -0,0 +1,31 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// A representation of all the possible errors that the ``AmiiboService`` service could throw.
public enum AmiiboServiceError: Error {
/// A bad request has been given to the client.
case badRequest
/// A response cannot be decoded.
case decoding
/// An online service is not currently available.
case notAvailable
/// A response cannot be found.
case notFound
/// An undocumented/unsupported status code error.
case undocumented(_ statusCode: Int)
/// An unknown error.
case unknown
}
// MARK: - Equatable
extension AmiiboServiceError: Equatable {}
Sources/AmiiboService/Public/Filters/AmiiboFilter.swift
+74
View File
@@ -0,0 +1,74 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// A type that contains values to fine-tune a response when requesting amiibo items.
public struct AmiiboFilter {
// MARK: Properties
/// A game character to return, if any.
public let gameCharacter: String?
/// A game series to return, if any.
public let gameSeries: String?
/// An amiibo identifier to return, if any.
public let identifier: String?
/// An amiibo name to return, if any.
public let name: String?
/// An amiibo series to return, if any.
public let series: String?
/// A flag indicating whether to include games in the response, if any.
public let showGames: Bool?
/// A flag indicating whether to include amiibo usages in games in the response, if any.
public let showUsage: Bool?
/// An amiibo type to return, if any.
public let type: String?
// MARK: Initializers
/// Initializes this filter.
/// - Parameters:
/// - identifier: An amiibo identifier to return, if any.
/// - name: An amiibo name to return, if any.
/// - type: An amiibo type to return, if any.
/// - series: An amiibo series to return, if any.
/// - gameCharacter: A game character to return, if any.
/// - gameSeries: A game series to return, if any.
/// - showGames: A flag indicating whether to include games in the response, if any.
/// - showUsage: A flag indicating whether to include amiibo usages in games in the response, if any.
public init(
identifier: String? = nil,
name: String? = nil,
type: String? = nil,
series: String? = nil,
gameCharacter: String? = nil,
gameSeries: String? = nil,
showGames: Bool? = nil,
showUsage: Bool? = nil
) {
self.gameCharacter = gameCharacter
self.gameSeries = gameSeries
self.identifier = identifier
self.name = name
self.series = series
self.showGames = showGames
self.showUsage = showUsage
self.type = type
}
}
Sources/AmiiboService/Public/Filters/AmiiboSeriesFilter.swift
+48
View File
@@ -0,0 +1,48 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// A type that contains values to fine-tune a response when requesting amiibo series.
public struct AmiiboSeriesFilter: KeyNameFilter {
// TODO: Remove the documentation from the properties and initializers of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
// MARK: Properties
/// A key to return, if any.
public let key: String?
/// A name to return, if any.
public let name: String?
// MARK: Initializers
/// Initializes this filter without key or name values.
public init() {
self.key = nil
self.name = nil
}
/// Initializes this filter with a key value.
/// - Parameter key: A key to return.
public init(key: String) {
self.key = key
self.name = nil
}
/// Initializes this filter with a name value.
/// - Parameter name: A name to return.
public init(name: String) {
self.key = nil
self.name = name
}
}
Sources/AmiiboService/Public/Filters/AmiiboTypeFilter.swift
+48
View File
@@ -0,0 +1,48 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// A type that contains values to fine-tune a response when requesting amiibo types.
public struct AmiiboTypeFilter: KeyNameFilter {
// TODO: Remove the documentation from the properties and initializers of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
// MARK: Properties
/// A key to return, if any.
public let key: String?
/// A name to return, if any.
public let name: String?
// MARK: Initializers
/// Initializes this filter without key or name values.
public init() {
self.key = nil
self.name = nil
}
/// Initializes this filter with a key value.
/// - Parameter key: A key to return.
public init(key: String) {
self.key = key
self.name = nil
}
/// Initializes this filter with a name value.
/// - Parameter name: A name to return.
public init(name: String) {
self.key = nil
self.name = name
}
}
Sources/AmiiboService/Public/Filters/GameCharacterFilter.swift
+48
View File
@@ -0,0 +1,48 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// A type that contains values to fine-tune a response when requesting game characters.
public struct GameCharacterFilter: KeyNameFilter {
// TODO: Remove the documentation from the properties and initializers of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
// MARK: Properties
/// A key to return, if any.
public let key: String?
/// A name to return, if any.
public let name: String?
// MARK: Initializers
/// Initializes this filter without key or name values.
public init() {
self.key = nil
self.name = nil
}
/// Initializes this filter with a key value.
/// - Parameter key: A key to return.
public init(key: String) {
self.key = key
self.name = nil
}
/// Initializes this filter with a name value.
/// - Parameter name: A name to return.
public init(name: String) {
self.key = nil
self.name = name
}
}
Sources/AmiiboService/Public/Filters/GameSeriesFilter.swift
+48
View File
@@ -0,0 +1,48 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// A type that contains values to fine-tune a response when requesting game series.
public struct GameSeriesFilter: KeyNameFilter {
// TODO: Remove the documentation from the properties and initializers of this type as the `--enable-inherited-docs` flag when generating DocC documentation is not working as intended (?).
// MARK: Properties
/// A key to return, if any.
public let key: String?
/// A name to return, if any.
public let name: String?
// MARK: Initializers
/// Initializes this filter without key or name values.
public init() {
self.key = nil
self.name = nil
}
/// Initializes this filter with a key value.
/// - Parameter key: A key to return.
public init(key: String) {
self.key = key
self.name = nil
}
/// Initializes this filter with a name value.
/// - Parameter name: A name to return.
public init(name: String) {
self.key = nil
self.name = name
}
}
Sources/AmiiboService/Public/Models/Amiibo.swift
+83
View File
@@ -0,0 +1,83 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
import Foundation
/// A model that represents an amiibo item.
public struct Amiibo: Sendable {
// MARK: Properties
/// A game character.
public let gameCharacter: String
/// A game series.
public let gameSeries: String
/// The first 8 hexadecimal characters of an identifier.
public let head: String
/// An image link.
public let image: String
/// An amiibo name.
public let name: String
/// A game platform type, if any.
public let platform: Platform?
/// A release date.
public let release: Release
/// An amiibo series.
public let series: String
/// The last 8 hexadecimal characters of an identifier.
public let tail: String
/// An amiibo type.
public let type: 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.Amiibo) {
self.gameCharacter = payload.character
self.gameSeries = payload.gameSeries
self.head = payload.head
self.image = payload.image
self.name = payload.name
self.platform = .init(
payload.gamesSwitch,
payload.games3DS,
payload.gamesWiiU
)
self.release = .init(payload.release)
self.series = payload.amiiboSeries
self.tail = payload.tail
self.type = payload._type
}
// MARK: Computed
/// An identifier.
public var identifier: String {
head + tail
}
/// A URL related to an image link, if any.
public var imageURL: URL? {
.init(string: image)
}
}
Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Game.swift
+45
View File
@@ -0,0 +1,45 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
extension Amiibo {
/// A model that represents a game related to an amiibo item.
public struct Game: Sendable {
// MARK: Properties
/// A list of identifiers.
public let identifiers: [String]
/// A name.
public let name: String
/// A list of amiibo usages, if any.
public let usages: [Usage]?
// MARK: Initializers
/// Initializes this model from a given payload.
/// - Parameter payload: A payload that contains the values for the model.
init(_ payload: Components.Schemas.AmiiboGame) {
self.identifiers = payload.gameID
self.name = payload.gameName
self.usages = {
guard let usages = payload.amiiboUsage else {
return nil
}
return usages.map { .init($0) }
}()
}
}
}
Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Platform.swift
+65
View File
@@ -0,0 +1,65 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
extension Amiibo {
/// A model that represents a collection of `WiiU`, `3DS`, and `Switch` games related to an amiibo item.
public struct Platform: Sendable {
// MARK: Properties
/// A list of `Switch` games related to an amiibo item.
public let `switch`: [Game]
/// A list of `3DS` games related to an amiibo item.
public let threeDS: [Game]
/// A list of `WiiU` games related to an amiibo item.
public let wiiU: [Game]
// MARK: Initialisers
/// Initializes this model.
///
/// > important: In case no data is provided, then an instance of this model is not created.
///
/// - Parameters:
/// - switch: A list of `Switch` games related to an amiibo item, if any.
/// - threeDS: A list of `3DS` games related to an amiibo item, if any.
/// - wiiU: A list of `WiiU` games related to an amiibo item, if any.
init?(
_ `switch`: [Components.Schemas.AmiiboGame]?,
_ threeDS: [Components.Schemas.AmiiboGame]?,
_ wiiU: [Components.Schemas.AmiiboGame]?
) {
guard (`switch` != nil && `switch`?.isEmpty == false)
|| (threeDS != nil && threeDS?.isEmpty == false)
|| (wiiU != nil && wiiU?.isEmpty == false)
else {
return nil
}
self.switch = {
guard let `switch` else { return [] }
return `switch`.map { .init($0) }
}()
self.threeDS = {
guard let threeDS else { return [] }
return threeDS.map { .init($0) }
}()
self.wiiU = {
guard let wiiU else { return [] }
return wiiU.map { .init($0) }
}()
}
}
}
Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Release.swift
+45
View File
@@ -0,0 +1,45 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
import Foundation
extension Amiibo {
/// A model that represents a collection of release dates related to an amiibo item.
public struct Release: Sendable {
// MARK: Properties
/// A release date for North America, if any.
public let america: Date?
/// A release date for Australia, if any.
public let australia: Date?
/// A release date for Europe, if any.
public let europe: Date?
/// A release date for Japan, if any.
public let japan: Date?
// MARK: Initializers
/// Initializes this model from a given payload.
/// - Parameter payload: A payload that contains the values for the model.
init(_ payload: Components.Schemas.AmiiboRelease) {
self.america = payload.na
self.australia = payload.au
self.europe = payload.eu
self.japan = payload.jp
}
}
}
Sources/AmiiboService/Public/Models/Amiibo/Amiibo+Usage.swift
+35
View File
@@ -0,0 +1,35 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
extension Amiibo {
/// A model that represents the usage of an amiibo item within a certain game.
public struct Usage: Sendable {
// MARK: Properties
/// An explanation of how to use an amiibo item.
public let explanation: String
/// A flag that indicates whether an amiibo item can save game data in it.
public let isWriteable: Bool
// MARK: Initializers
/// Initializes this model from a given payload.
/// - Parameter payload: A payload that contains the values for the model.
init(_ payload: Components.Schemas.AmiiboUsage) {
self.explanation = payload.Usage
self.isWriteable = payload.write
}
}
}
Sources/AmiiboService/Public/Models/AmiiboSeries.swift
+33
View File
@@ -0,0 +1,33 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// 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.
public let key: String
/// A name.
public let name: String
// MARK: Initializers
init(_ payload: Components.Schemas.Tuple) {
self.key = payload.key
self.name = payload.name
}
}
Sources/AmiiboService/Public/Models/AmiiboType.swift
+33
View File
@@ -0,0 +1,33 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// 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.
public let key: String
/// A name.
public let name: String
// MARK: Initializers
init(_ payload: Components.Schemas.Tuple) {
self.key = payload.key
self.name = payload.name
}
}
Sources/AmiiboService/Public/Models/GameCharacter.swift
+33
View File
@@ -0,0 +1,33 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// 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.
public let key: String
/// A name.
public let name: String
// MARK: Initializers
init(_ payload: Components.Schemas.Tuple) {
self.key = payload.key
self.name = payload.name
}
}
Sources/AmiiboService/Public/Models/GameSeries.swift
+33
View File
@@ -0,0 +1,33 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
/// 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.
public let key: String
/// A name.
public let name: String
// MARK: Initializers
init(_ payload: Components.Schemas.Tuple) {
self.key = payload.key
self.name = payload.name
}
}
Sources/AmiiboService/Public/Services/AmiiboService.swift
+93
View File
@@ -0,0 +1,93 @@
//===----------------------------------------------------------------------===
//
// This source file is part of the AmiiboService open source project
//
// Copyright (c) 2024-2025 Röck+Cöde VoF. and the AmiiboAPI project authors
// Licensed under the EUPL 1.2 or later.
//
// See LICENSE for license information
// See CONTRIBUTORS for the list of AmiiboAPI project authors
//
//===----------------------------------------------------------------------===
import Foundation
/// A type that implements the service that uses a client to make calls.
public struct AmiiboService {
// MARK: Properties
/// A client to interact with the endpoints.
private let client: any APIClient
// MARK: Initializers
/// Initializes this service with a specific client type.
/// - Parameter client: A representation of a client to use to interact with the endpoints.
public init(_ client: AmiiboClient) {
self.client = switch client {
case let .mock(mockClient): mockClient
case let .live(liveClient): liveClient
}
}
// MARK: Functions
/// Gets a list of amiibo items based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered amiibo items.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getAmiibos(
_ filter: AmiiboFilter = .init()
) async throws(AmiiboServiceError) -> [Amiibo] {
try await client.getAmiibos(by: filter)
}
/// Gets a list of amiibo series based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered amiibo series.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getAmiiboSeries(
_ filter: AmiiboSeriesFilter = .init()
) async throws(AmiiboServiceError) -> [AmiiboSeries] {
try await client.getAmiiboSeries(by: filter)
}
/// Gets a list of amiibo types based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered amiibo types.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getAmiiboTypes(
_ filter: AmiiboTypeFilter = .init()
) async throws(AmiiboServiceError) -> [AmiiboType] {
try await client.getAmiiboTypes(by: filter)
}
/// Gets a list of game characters based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered game characters.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getGameCharacters(
_ filter: GameCharacterFilter = .init()
) async throws(AmiiboServiceError) -> [GameCharacter] {
try await client.getGameCharacters(by: filter)
}
/// Gets a list of game series based on a given filter.
/// - Parameter filter: A filter to remove unwanted items from the result.
/// - Returns: A list of filtered game series.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getGameSeries(
_ filter: GameSeriesFilter = .init()
) async throws(AmiiboServiceError) -> [GameSeries] {
try await client.getGameSeries(by: filter)
}
/// Gets the date when the data was last updated.
/// - Returns: A last updated date.
/// - Throws: An ``AmiiboServiceError`` error in case some issue is encountered while generating the result.
public func getLastUpdated() async throws(AmiiboServiceError) -> Date {
try await client.getLastUpdated()
}
}