diff --git a/Sources/DiscogsService/Catalogs/DiscogsService.docc/Library.md b/Sources/DiscogsService/Catalogs/DiscogsService.docc/Library.md index 89debd031..d1df13773 100644 --- a/Sources/DiscogsService/Catalogs/DiscogsService.docc/Library.md +++ b/Sources/DiscogsService/Catalogs/DiscogsService.docc/Library.md @@ -1,10 +1,10 @@ # ``DiscogsService`` -Summary +A Swift client library for the Discogs API, built on top of Swift OpenAPI. ## Overview -Text +This library provides a type-safe client for interacting with the [Discogs API](https://www.discogs.com/developers), including endpoints for the database, user identity, user collections, wantlists, lists, and the marketplace. It supports multiple authentication methods and transports credentials via headers or query parameters. ## Topics diff --git a/Sources/DiscogsService/Internal/Extensions/String+Constants.swift b/Sources/DiscogsService/Internal/Extensions/String+Constants.swift index b88780dc1..45effa4f8 100644 --- a/Sources/DiscogsService/Internal/Extensions/String+Constants.swift +++ b/Sources/DiscogsService/Internal/Extensions/String+Constants.swift @@ -16,7 +16,7 @@ extension String { /// An empty string. static let empty = "" - /// A namespaces assigned for the names of parameters. + /// A namespace for the names of parameters. enum Parameter { /// A name for the consumer key. static let key = "key" @@ -25,9 +25,9 @@ extension String { /// A name for the user token. static let token = "token" } - /// A namespaces assigned for the formats of string values. + /// A namespace for the formats of string values. enum Format {} - /// A namespaces assigned for the formats of regular expression patterns. + /// A namespace for the formats of regular expression patterns. enum Pattern {} } diff --git a/Sources/DiscogsService/Internal/Validation Rules/CamelCaseValidationRule.swift b/Sources/DiscogsService/Internal/Validation Rules/CamelCaseValidationRule.swift index a3803f645..62caa523c 100644 --- a/Sources/DiscogsService/Internal/Validation Rules/CamelCaseValidationRule.swift +++ b/Sources/DiscogsService/Internal/Validation Rules/CamelCaseValidationRule.swift @@ -52,7 +52,7 @@ private extension CamelCaseValidationRule { /// /// - Parameter input: An input to be validated. /// - Returns: A flag that indicates whether a given input has been validated or not. - /// - Throws: An error of type ``InputValidatorError`` in case the validation failed. + /// - Throws: An error of type ``InputValidationError`` in case the validation failed. func validate(input: String?) throws -> Bool { guard let input else { return false diff --git a/Sources/DiscogsService/Internal/Validation Rules/NotEmptyValidationRule.swift b/Sources/DiscogsService/Internal/Validation Rules/NotEmptyValidationRule.swift index 0cea11167..4cea0458a 100644 --- a/Sources/DiscogsService/Internal/Validation Rules/NotEmptyValidationRule.swift +++ b/Sources/DiscogsService/Internal/Validation Rules/NotEmptyValidationRule.swift @@ -52,7 +52,7 @@ private extension NotEmptyValidationRule { /// /// - Parameter input: An input to be validated. /// - Returns: A flag that indicates whether a given input has been validated or not. - /// - Throws: An error of type ``InputValidatorError`` in case the validation failed. + /// - Throws: An error of type ``InputValidationError`` in case the validation failed. func validate(input: String?) throws -> Bool { guard let input else { return false diff --git a/Sources/DiscogsService/Internal/Validation Rules/NotNilValidationRule.swift b/Sources/DiscogsService/Internal/Validation Rules/NotNilValidationRule.swift index ce59354a6..db1821480 100644 --- a/Sources/DiscogsService/Internal/Validation Rules/NotNilValidationRule.swift +++ b/Sources/DiscogsService/Internal/Validation Rules/NotNilValidationRule.swift @@ -52,7 +52,7 @@ private extension NotNilValidationRule { /// /// - Parameter input: An input to be validated. /// - Returns: A flag that indicates whether a given input has been validated or not. - /// - Throws: An error of type ``InputValidatorError`` in case the validation failed. + /// - Throws: An error of type ``InputValidationError`` in case the validation failed. func validate(input: String?) throws -> Bool { guard input != nil else { throw InputValidationError.inputIsNil diff --git a/Sources/DiscogsService/Internal/Validation Rules/SecureValidationRule.swift b/Sources/DiscogsService/Internal/Validation Rules/SecureValidationRule.swift index 5f073555f..27a7a0223 100644 --- a/Sources/DiscogsService/Internal/Validation Rules/SecureValidationRule.swift +++ b/Sources/DiscogsService/Internal/Validation Rules/SecureValidationRule.swift @@ -65,9 +65,9 @@ extension InputValidationRule where Self == SecureValidationRule { enum SecurityInput: Int { /// A consumer key is 20 characters long. case consumerKey = 20 - /// A consumer key is 32 characters long. + /// A consumer secret is 32 characters long. case consumerSecret = 32 - /// A consumer key is 40 characters long. + /// A user token is 40 characters long. case userToken = 40 } @@ -83,7 +83,7 @@ private extension SecureValidationRule { /// /// - Parameter input: An input to be validated. /// - Returns: A flag that indicates whether a given input has been validated or not. - /// - Throws: An error of type ``InputValidatorError`` in case the validation failed. + /// - Throws: An error of type ``InputValidationError`` in case the validation failed. func validate(input: String?) throws -> Bool { guard let input else { return false diff --git a/Sources/DiscogsService/Internal/Validation Rules/SemanticVersionValidationRule.swift b/Sources/DiscogsService/Internal/Validation Rules/SemanticVersionValidationRule.swift index 61921391e..1f303caa7 100644 --- a/Sources/DiscogsService/Internal/Validation Rules/SemanticVersionValidationRule.swift +++ b/Sources/DiscogsService/Internal/Validation Rules/SemanticVersionValidationRule.swift @@ -54,7 +54,7 @@ private extension SemanticVersionValidationRule { /// /// - Parameter input: An input to be validated. /// - Returns: A flag that indicates whether a given input has been validated or not. - /// - Throws: An error of type ``InputValidatorError`` in case the validation failed. + /// - Throws: An error of type ``InputValidationError`` in case the validation failed. func validate(input: String?) throws -> Bool { guard let input else { return false diff --git a/Sources/DiscogsService/Internal/Validation Rules/URLValidationRule.swift b/Sources/DiscogsService/Internal/Validation Rules/URLValidationRule.swift index 3c5d443e5..144cc1129 100644 --- a/Sources/DiscogsService/Internal/Validation Rules/URLValidationRule.swift +++ b/Sources/DiscogsService/Internal/Validation Rules/URLValidationRule.swift @@ -56,7 +56,7 @@ private extension URLValidationRule { /// /// - Parameter input: An input to be validated. /// - Returns: A flag that indicates whether a given input has been validated or not. - /// - Throws: An error of type ``InputValidatorError`` in case the validation failed. + /// - Throws: An error of type ``InputValidationError`` in case the validation failed. func validate(input: String?) throws -> Bool { guard let input else { return false diff --git a/Sources/DiscogsService/Public/Definitions/References.swift b/Sources/DiscogsService/Public/Definitions/References.swift index d85cbf308..d938eade1 100644 --- a/Sources/DiscogsService/Public/Definitions/References.swift +++ b/Sources/DiscogsService/Public/Definitions/References.swift @@ -12,5 +12,7 @@ // // ===----------------------------------------------------------------------=== -/// A reference to a live (or production) service defined in the OpenAPI document. +/// A type alias for the live (production) Discogs API server defined in the OpenAPI document. +/// +/// Use this as the `serverURL` when initializing a ``Client`` to connect to the production Discogs API. public typealias LiveService = Servers.Server1 diff --git a/Sources/DiscogsService/Public/Enumerations/AuthTransport.swift b/Sources/DiscogsService/Public/Enumerations/AuthTransport.swift index e8ecb2101..1a6004535 100644 --- a/Sources/DiscogsService/Public/Enumerations/AuthTransport.swift +++ b/Sources/DiscogsService/Public/Enumerations/AuthTransport.swift @@ -13,8 +13,11 @@ // ===----------------------------------------------------------------------=== /// A representation of the available transport options to send credentials in authenticated requests. +/// +/// This enumeration is used in conjunction with ``AuthMiddleware`` to determine how authentication credentials +/// are attached to outgoing requests. public enum AuthTransport: CaseIterable, Sendable { - /// Authentication credential are sent in a request as an `Authentication` header. + /// Authentication credentials are sent in a request as an `Authorization` header. /// /// This means that the header will be added to any existing header in a request, like this: /// ```bash @@ -22,7 +25,7 @@ public enum AuthTransport: CaseIterable, Sendable { /// curl "https://api.discogs.com/database/search?q=Slayer" -H "Authorization: Discogs token=abcxyz123456" /// ``` case onHeader - /// Authentication credential are sent in a request as parameters in the query string. + /// Authentication credentials are sent in a request as parameters in the query string. /// /// This means that the parameters will be injected into the query in a request, like this: /// ```bash diff --git a/Sources/DiscogsService/Public/Errors/InputValidationError.swift b/Sources/DiscogsService/Public/Errors/InputValidationError.swift index 7fcb236e5..7c0db3e10 100644 --- a/Sources/DiscogsService/Public/Errors/InputValidationError.swift +++ b/Sources/DiscogsService/Public/Errors/InputValidationError.swift @@ -12,7 +12,7 @@ // // ===----------------------------------------------------------------------=== -/// A representation of all the possible validation error that could be thrown while validating an input. +/// A representation of all the possible validation errors that could be thrown while validating an input. public enum InputValidationError: Error { /// An input is empty. case inputIsEmpty diff --git a/Sources/DiscogsService/Public/Middlewares/AuthMiddleware.swift b/Sources/DiscogsService/Public/Middlewares/AuthMiddleware.swift index 2ac39dc7e..3c5d8a445 100644 --- a/Sources/DiscogsService/Public/Middlewares/AuthMiddleware.swift +++ b/Sources/DiscogsService/Public/Middlewares/AuthMiddleware.swift @@ -110,6 +110,14 @@ extension AuthMiddleware: ClientMiddleware { // MARK: Functions + /// Intercepts an outgoing HTTP request and injects authentication credentials if configured. + /// - Parameters: + /// - request: The outgoing HTTP request to potentially authenticate. + /// - body: The optional body of the HTTP request. + /// - baseURL: The base URL of the service. + /// - operationID: The identifier of the API operation being called. + /// - next: The next middleware or transport to call in the chain. + /// - Returns: The HTTP response and optional response body from the service. public func intercept( _ request: HTTPRequest, body: HTTPBody?, diff --git a/Sources/DiscogsService/Public/Middlewares/UserAgentMiddleware.swift b/Sources/DiscogsService/Public/Middlewares/UserAgentMiddleware.swift index 8d3fa2336..4eea71878 100644 --- a/Sources/DiscogsService/Public/Middlewares/UserAgentMiddleware.swift +++ b/Sources/DiscogsService/Public/Middlewares/UserAgentMiddleware.swift @@ -60,6 +60,14 @@ extension UserAgentMiddleware: ClientMiddleware { // MARK: Functions + /// Intercepts an outgoing HTTP request and attaches the `User-Agent` header. + /// - Parameters: + /// - request: The outgoing HTTP request to modify. + /// - body: The optional body of the HTTP request. + /// - baseURL: The base URL of the service. + /// - operationID: The identifier of the API operation being called. + /// - next: The next middleware or transport to call in the chain. + /// - Returns: The HTTP response and optional response body from the service. public func intercept( _ request: HTTPRequest, body: HTTPBody?, diff --git a/Sources/DiscogsService/Public/Models/Product.swift b/Sources/DiscogsService/Public/Models/Product.swift index ba23432ff..af179ae80 100644 --- a/Sources/DiscogsService/Public/Models/Product.swift +++ b/Sources/DiscogsService/Public/Models/Product.swift @@ -14,27 +14,32 @@ import Foundation -/// A type that represents a product that uses the ``Client`` client. +/// A representation of the product information used to generate the `User-Agent` header for requests to the Discogs API. +/// +/// The Discogs API requires a `User-Agent` header that identifies the application making the request. This model captures +/// the product name, version, and URL needed to build that header via the ``UserAgentMiddleware``. +/// +/// The generated `User-Agent` header follows the format: `ProductName/1.0.0 +https://example.com` public struct Product: Sendable { // MARK: Properties - /// A camel-cased name of a product. + /// The camel-cased name of the product (e.g., `MyDiscogsApp`). let name: String - /// A URI link related to a product. + /// A URI link related to the product (e.g., `https://example.com`). let url: String - /// A semantic version of a product. + /// The semantic version of the product (e.g., `1.0.0`). let version: String // MARK: Initializers /// Initializes this model. /// - Parameters: - /// - name: A camel-cased name of a product. - /// - version: A semantic version of a product. - /// - url: A URI link related to a product. + /// - name: The camel-cased name of the product. + /// - version: The semantic version of the product, following [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). + /// - url: A URI link related to the product. public init( name: String, version: String,