Patched (temporarily) the DocC documentation (#8)
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:
@@ -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 }
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
Reference in New Issue
Block a user