From 5f271b2818105d90d7cce608bca63c65e95c0546 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 9 Oct 2025 18:21:31 +0200
Subject: [PATCH] Implemented the GET /releases/{release-id}/stats endpoint for
 the Open API specification documentation in the library target.

---
 Sources/DiscogsService/openapi.yaml | 42 +++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml
index 938362355..4066b9fbd 100644
--- a/Sources/DiscogsService/openapi.yaml
+++ b/Sources/DiscogsService/openapi.yaml
@@ -479,6 +479,33 @@ paths:
                 $ref: '#/components/schemas/ReleaseRatingByUser'
         '404':
           $ref: '#/components/responses/NotFound'
+  /releases/{release_id}/stats:
+    get:
+      tags:
+        - Database
+      summary: Get information about statistics of release.
+      description: Retrieves the total number of “haves” (in the community's collections) and “wants” (in the community's wantlists) for a given release.
+      operationId: getReleaseStats
+      parameters:
+        - $ref: '#/components/parameters/ReleaseId'
+      responses:
+        '200':
+          description: |
+            Successfully retrieved release rating details by a given user.
+
+            > warning: There is a discrepancy about this response between was is documented and what the endpoints actually responds. In the [documentation](https://www.discogs.com/developers#page:database,header:database-release-stats), it is defined that a type containing a statistical data would be returned but the actual response returns an object that contains a boolean flag instead.
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/ReleaseStats'
+                  - type: object
+                    properties:
+                      is_offensive:
+                        type: boolean
+                        required: true
+        '404':
+          $ref: '#/components/responses/NotFound'    
 components:
   schemas:
     Artist:
@@ -1131,6 +1158,21 @@ components:
         - rating
         - release_id
         - username
+    ReleaseStats:
+      description: A type that represents the statistics of a release.
+      type: object
+      properties:
+        num_have:
+          description: A total number of users that have a release in their collection.
+          type: integer
+          minimum: 0
+        num_want:
+          description: A total number of users that have a release in their wantlist.
+          type: integer
+          minimum: 0
+      required:
+        - num_have
+        - num_want
     ReleaseVersion:
       description: A type that represents a version of a release.
       type: object