From a5c7a53e1e9ebc434b205023c28c5533873062d2 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 16 Oct 2025 19:23:56 +0200
Subject: [PATCH] Implemented the GET /lists/{list_id} endpoint for the Open
 API specification document in the library target.

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

diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml
index ef1eeca5f..764f4caeb 100644
--- a/Sources/DiscogsService/openapi.yaml
+++ b/Sources/DiscogsService/openapi.yaml
@@ -1785,6 +1785,36 @@ paths:
           $ref: '#/components/responses/NotFound'
         '500':
           $ref: '#/components/responses/InternalError'
+  /lists/{list_id}:
+    get:
+      tags:
+        - User Lists
+      summary: Get items from a specified list.
+      description: |
+        Returns items from a specified list.
+        
+        Private lists are not shown unless a user is authenticated as an owner.
+      operationId: getList
+      parameters:
+        - $ref: '#/components/parameters/ListId'
+      responses:
+        '200':
+          description: Successfully retrieved the items associated with a specified list.
+          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/List'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalError'
 components:
   headers:
     Link:
@@ -1945,6 +1975,15 @@ components:
       schema:
         type: integer
       example: 1
+    ListId:
+      description: An identifier of a list.
+      name: list_id
+      in: path
+      required: true
+      schema:
+        type: integer
+        minimum: 0
+      example: 123
     Location:
       description: A geographical location of a user.
       name: location
@@ -2645,6 +2684,96 @@ components:
         - public
         - resource_url
         - uri
+    List:
+      description: A type that represents a list.
+      type: object
+      properties:
+        list_id:
+          description: An identifier of a list.
+          type: integer
+          minimum: 0
+          readOnly: true
+        resource_url:
+          description: A URI resource of a list.
+          type: string
+          format: uri
+          readOnly: true
+        url:
+          description: A URL representation of a list.
+          type: string
+          format: uri
+        name: 
+          description: A name of a list.
+          type: string
+        description: 
+          description: A descriptive explanation of a list.
+          type: string
+        public:
+          description: A flag that indicates whether a list is public or not.
+          type: boolean
+        created_ts:
+          description: A date and time in which a list was created.
+          type: string
+          format: date-time
+        modified_ts:
+          description: A date and time in which a list was last modified.
+          type: string
+          format: date-time
+        items:
+          description: A list of items contained by a list
+          type: array
+          items:
+            description: A type that represents a list item.
+            type: object
+            properties:
+              id:
+                description: An identifier of a list item.
+                type: integer
+                minimum: 0
+                readOnly: true
+              uri: 
+                description: A URI representation of a list item.
+                type: string
+                format: uri
+                readOnly: true
+              resource_url: 
+                description: A URI resource of a list item.
+                type: string
+                format: uri
+                readOnly: true
+              type:
+                description: A type of a list item.
+                type: string
+                enum:
+                  - artist
+                  - label
+                  - release
+              display_title:
+                description: A display title of a list item.
+                type: string
+              image_url:
+                description: An image URL associated with a list item.
+                type: string
+                format: uri
+              comment:
+                description: A comment associated with a list item.
+                type: string
+            required:
+              - display_title
+              - id
+              - image_url
+              - resource_url
+              - type
+              - uri
+      required: 
+        - created_ts
+        - description
+        - list_id
+        - modified_ts
+        - name
+        - public
+        - resource_url
+        - url
     Master:
       description: A type that represents a set of similar releases.
       type: object