Improved the source code documentation of the source code in the package.
This commit is contained in:
@@ -1,10 +1,10 @@
|
||||
# ``DiscogsService``
|
||||
|
||||
<!--@START_MENU_TOKEN@-->Summary<!--@END_MENU_TOKEN@-->
|
||||
A Swift client library for the Discogs API, built on top of Swift OpenAPI.
|
||||
|
||||
## Overview
|
||||
|
||||
<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
|
||||
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
|
||||
|
||||
|
||||
@@ -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 {}
|
||||
}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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?,
|
||||
|
||||
@@ -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?,
|
||||
|
||||
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user