rock-n-code/discogs-service
1
0
Fork 0
Code Pull Requests Releases 8 Activity

Documentation improvements (#16)

Browse Source 
This PR contains the work done to improve the documentation efforts in the package, aiming at improving the documentation of the source code as well as the OpenAPI specification document. In addition, a breaking bug has been fixed.

Reviewed-on: #16
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 #16.
This commit is contained in:
Javier Cicchelli
2026-03-24 01:22:53 +00:00
committed by Javier Cicchelli
parent a0672cc4af
commit b14a9fa816
35 changed files with 196 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/DiscogsService/Public/Definitions/References.swift
+4 -2
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the DiscogsService open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the DiscogsService project authors
// Copyright (c) 2026 Röck+Cöde VoF. and the DiscogsService project authors
// Licensed under Apache license v2.0
//
// See LICENSE for license information
@@ -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
Sources/DiscogsService/Public/Enumerations/AuthMethod.swift
+1 -1
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the DiscogsService open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the DiscogsService project authors
// Copyright (c) 2026 Röck+Cöde VoF. and the DiscogsService project authors
// Licensed under Apache license v2.0
//
// See LICENSE for license information
Sources/DiscogsService/Public/Enumerations/AuthTransport.swift
+6 -3
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the DiscogsService open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the DiscogsService project authors
// Copyright (c) 2026 Röck+Cöde VoF. and the DiscogsService project authors
// Licensed under Apache license v2.0
//
// See LICENSE for license information
@@ -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
Sources/DiscogsService/Public/Errors/InputValidationError.swift
+2 -2
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the DiscogsService open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the DiscogsService project authors
// Copyright (c) 2026 Röck+Cöde VoF. and the DiscogsService project authors
// Licensed under Apache license v2.0
//
// See LICENSE for license information
@@ -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
Sources/DiscogsService/Public/Middlewares/AuthMiddleware.swift
+9 -1
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the DiscogsService open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the DiscogsService project authors
// Copyright (c) 2026 Röck+Cöde VoF. and the DiscogsService project authors
// Licensed under Apache license v2.0
//
// See LICENSE for license information
@@ -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?,
Sources/DiscogsService/Public/Middlewares/UserAgentMiddleware.swift
+9 -1
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the DiscogsService open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the DiscogsService project authors
// Copyright (c) 2026 Röck+Cöde VoF. and the DiscogsService project authors
// Licensed under Apache license v2.0
//
// See LICENSE for license information
@@ -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?,
Sources/DiscogsService/Public/Models/Product.swift
+13 -8
View File
@@ -2,7 +2,7 @@
//
// This source file is part of the DiscogsService open source project
//
// Copyright (c) 2025 Röck+Cöde VoF. and the DiscogsService project authors
// Copyright (c) 2026 Röck+Cöde VoF. and the DiscogsService project authors
// Licensed under Apache license v2.0
//
// See LICENSE for license information
@@ -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,