Implemented the missing Database endpoints (#8)

This PR contains the work done to declare the missing, non-GET endpoints of the *Database* section in the [Discogs API documentation](https://www.discogs.com/developers#page:database) into the `OpenAPI` specification document.

Furthermore, documentation extensions have been defined for the `APIProtocol` and `Client` types in the `DocC` documentation catalog to match the categories of these endpoint calls to the categories in the Discogs documentation.

Reviewed-on: #8
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

Sources/DiscogsService/Catalogs/DiscogsService.docc/Extensions/APIProtocol.md

@@ -0,0 +1,37 @@
+# ``APIProtocol``
+
+## Topics
+
+### Service endpoints
+
+- ``APIProtocol/getService(_:)``
+- ``APIProtocol/getService(headers:)``
+
+### Database endpoints
+
+- ``APIProtocol/searchDatabase(_:)``
+- ``APIProtocol/searchDatabase(query:headers:)``
+- ``APIProtocol/getArtist(_:)``
+- ``APIProtocol/getArtist(path:headers:)``
+- ``APIProtocol/getArtistReleases(_:)``
+- ``APIProtocol/getArtistReleases(path:query:headers:)``
+- ``APIProtocol/getLabel(_:)``
+- ``APIProtocol/getLabel(path:headers:)``
+- ``APIProtocol/getLabelReleases(_:)``
+- ``APIProtocol/getLabelReleases(path:query:headers:)``
+- ``APIProtocol/getMaster(_:)``
+- ``APIProtocol/getMaster(path:headers:)``
+- ``APIProtocol/getMasterVersions(_:)``
+- ``APIProtocol/getMasterVersions(path:query:headers:)``
+- ``APIProtocol/getRelease(_:)``
+- ``APIProtocol/getRelease(path:query:headers:)``
+- ``APIProtocol/getReleaseRating(_:)``
+- ``APIProtocol/getReleaseRating(path:headers:)``
+- ``APIProtocol/getReleaseRatingByUser(_:)``
+- ``APIProtocol/getReleaseRatingByUser(path:headers:)``
+- ``APIProtocol/putReleaseRatingByUser(_:)``
+- ``APIProtocol/putReleaseRatingByUser(path:query:headers:)``
+- ``APIProtocol/deleteReleaseRatingByUser(_:)``
+- ``APIProtocol/deleteReleaseRatingByUser(path:headers:)``
+- ``APIProtocol/getReleaseStats(_:)``
+- ``APIProtocol/getReleaseStats(path:headers:)``

Sources/DiscogsService/Catalogs/DiscogsService.docc/Extensions/Client.md

@@ -0,0 +1,27 @@
+# ``Client``
+
+## Topics
+
+### Initializers
+
+- ``Client/init(serverURL:configuration:transport:middlewares:)``
+
+### Service endpoints
+
+- ``Client/getService(_:)``
+
+### Database endpoints
+
+- ``Client/searchDatabase(_:)``
+- ``Client/getArtist(_:)``
+- ``Client/getArtistReleases(_:)``
+- ``Client/getLabel(_:)``
+- ``Client/getLabelReleases(_:)``
+- ``Client/getMaster(_:)``
+- ``Client/getMasterVersions(_:)``
+- ``Client/getRelease(_:)``
+- ``Client/getReleaseRating(_:)``
+- ``Client/getReleaseRatingByUser(_:)``
+- ``Client/putReleaseRatingByUser(_:)``
+- ``Client/deleteReleaseRatingByUser(_:)``
+- ``Client/getReleaseStats(_:)``

Sources/DiscogsService/Catalogs/DiscogsService.docc/Library.md

@@ -14,7 +14,7 @@
 
 ### Servers
 
-- ``Servers/Server1``
+- ``LiveService``
 
 ### Authentication
 

Sources/DiscogsService/Public/Definitions/References.swift

@@ -0,0 +1,16 @@
+// ===----------------------------------------------------------------------===
+//
+// This source file is part of the DiscogsService open source project
+//
+// Copyright (c) 2025 Röck+Cöde VoF. and the DiscogsService project authors
+// Licensed under Apache license v2.0
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of DiscogsService project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// ===----------------------------------------------------------------------===
+
+/// A reference to a live (or production) service defined in the OpenAPI document.
+public typealias LiveService = Servers.Server1

Sources/DiscogsService/openapi.yaml

@@ -521,6 +521,38 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
   /releases/{release_id}/rating/{username}:
+    delete: 
+      tags:
+        - Database
+      summary: Delete information about a rating of release by a user.
+      description: |
+        Updates a rating of a release for a given user. 
+        
+        This endpoint requires authentication.
+      operationId: deleteReleaseRatingByUser
+      parameters: 
+        - $ref: '#/components/parameters/ReleaseId'
+        - $ref: '#/components/parameters/Username'
+      security:
+        - Token: []
+        - KeySecret: []
+        - OAuth: []
+      responses:
+        '200':
+          description: Successfully deleted a rating for a specific release by a given user.
+          headers:
+            X-Discogs-RateLimit:
+              $ref: '#/components/headers/RateLimit'
+            X-Discogs-RateLimit-Used:
+              $ref: '#/components/headers/RateLimitUsed'
+            X-Discogs-RateLimit-Remaining:
+              $ref: '#/components/headers/RateLimitRemaining'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalError'
     get:
       tags:
         - Database
@@ -546,6 +578,43 @@ paths:
                 $ref: '#/components/schemas/ReleaseRatingByUser'
         '404':
           $ref: '#/components/responses/NotFound'
+    put:
+      tags: 
+        - Database
+      summary: Update information about a rating of release by a user.
+      description: |
+        Updates a rating of a release for a given user. 
+        
+        This endpoint requires authentication.
+      operationId: putReleaseRatingByUser
+      parameters: 
+        - $ref: '#/components/parameters/ReleaseId'
+        - $ref: '#/components/parameters/Username'
+        - $ref: '#/components/parameters/Rating'
+      security:
+        - Token: []
+        - KeySecret: []
+        - OAuth: []
+      responses:
+        '200':
+          description: Successfully updated a rating for a specific release by a given user.
+          headers:
+            X-Discogs-RateLimit:
+              $ref: '#/components/headers/RateLimit'
+            X-Discogs-RateLimit-Used:
+              $ref: '#/components/headers/RateLimitUsed'
+            X-Discogs-RateLimit-Remaining:
+              $ref: '#/components/headers/RateLimitRemaining'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReleaseRatingByUser'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalError'
   /releases/{release_id}/stats:
     get:
       tags:
@@ -580,7 +649,7 @@ paths:
                     required:
                       - is_offensive
         '404':
-          $ref: '#/components/responses/NotFound'    
+          $ref: '#/components/responses/NotFound'
   /database/search:
     get:
       tags:
@@ -856,12 +925,15 @@ components:
         type: integer
         minimum: 1
         maximum: 100
-    Released:
-      description: A filter by release year.
-      name: released
+    Rating:
+      description: A number (between 1 and 5) for a rating of a release.
+      name: rating
       in: query
+      required: true
       schema:
-        type: string    
+        type: integer
+        minimum: 1
+        maximum: 5
     ReleaseId:
       description: An identifier of a release.
       name: release_id
@@ -870,6 +942,12 @@ components:
       schema:
         type: integer
       example: 249504
+    Released:
+      description: A filter by release year.
+      name: released
+      in: query
+      schema:
+        type: string    
     SortOrder:
       description: The order to sort the results. 
       name: sort_order