From 6ea0c58dd5c5f9945dcde5f32dbbf1090df0c187 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 9 Oct 2025 01:07:47 +0200
Subject: [PATCH] Implemented the GET /artists/{artist-id} endpoint for the
 Open API specification documentation in the library target.

---
 Sources/DiscogsService/openapi.yaml | 176 +++++++++++++++++++++++++++-
 1 file changed, 173 insertions(+), 3 deletions(-)

diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml
index 08ae627a9..e5a684ac8 100644
--- a/Sources/DiscogsService/openapi.yaml
+++ b/Sources/DiscogsService/openapi.yaml
@@ -245,11 +245,11 @@ tags:
 paths:
   /:
     get:
-      tags:
-        - Service
-      summary: Get service information.
+      summary: Get information about the service.
       description:  Retrieves any available information related to the service.
       operationId: getService
+      tags:
+        - Service
       responses: 
         '200':
           description: Service information returned successfully.
@@ -259,8 +259,161 @@ paths:
                 $ref: '#/components/schemas/Service'
         '500':
           $ref: '#/components/responses/Unavailable'
+  /artists/{artist_id}:
+    get:
+      summary: Get information about an artist.
+      operationId: getArtist
+      description: Retrieves any available information for a specific artist.
+      tags:
+        - Database
+      parameters:
+        - $ref: '#/components/parameters/ArtistId'
+      responses:
+        '200':
+          description: Successfully retrieved artist details.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Artist'
+        '404':
+          $ref: '#/components/responses/NotFound'
 components:
   schemas:
+    Artist:
+      description: A type that represents an artist or a group.
+      type: object
+      properties:
+        id:
+          description: An identifier of an artist.
+          type: integer
+          readOnly: true
+        name:
+          description: A name of an artist.
+          type: string
+        realname:
+          description: A real name of an artist, if any.
+          type: string
+        resource_url:
+          description: A URI resource of an artist.
+          type: string
+          format: uri
+          readOnly: true
+        uri:
+          description: A URI representation of an artist.
+          type: string
+          format: uri
+          readOnly: true
+        releases_url:
+          description: A URL to the releases of an artist.
+          type: string
+          format: uri
+        profile:
+          description: A detailed profile of an artist, if any.
+          type: string
+        urls:
+          description: A list of URLs related to an artist.
+          type: array
+          items:
+            type: string
+            format: uri
+        namevariations:
+          description: A list of name variations related to an artist.
+          type: array
+          items:
+            type: string
+        members:
+          description: A list of artists related to an artist (in case of group).
+          type: array
+          items:
+            $ref: '#/components/schemas/ArtistID'
+        images:
+          description: A list of images related to an artist.
+          type: array
+          items:
+            $ref: '#/components/schemas/Image'
+        data_quality:
+          description: An explanation for the data quality related to an artist.
+          type: string
+      required: 
+        - data_quality
+        - id
+        - name
+        - releases_url
+        - resource_url
+        - uri
+    ArtistID:
+      description: A type that references an artist.
+      type: object
+      properties:
+        id:
+          description: An identifier of an artist.
+          type: integer
+          readOnly: true
+        name:
+          description: A name of an artist.
+          type: string
+        resource_url:
+          description: A URI resource of an artist.
+          type: string
+          format: uri
+          readOnly: true
+        active:
+          description: A flag that indicates whether the relation is currently active or not.
+          type: boolean
+        anv:
+          description: TBD
+          type: string
+        join:
+          description: TBD
+          type: string
+        role:
+          description: TBD
+          type: string
+        tracks:
+          description: TBD
+          type: string
+      required:
+        - active
+        - id
+        - name
+        - resource_url
+    Image:
+      description: A type that represents an image of a resource.
+      type: object
+      properties:
+        type:
+          description: A type of an image.
+          type: string
+          enum: 
+            - primary
+            - secondary
+        uri:
+          description: A URI representation of an image.
+          type: string
+          format: uri
+          readOnly: true
+        resource_url:
+          description: A URI resource of an image.
+          type: string
+          format: uri
+          readOnly: true
+        uri150:
+          description: TBD
+          type: string
+          format: uri
+        width:
+          description: A width of an image (in pixels).
+          type: integer
+        height:
+          description: A height of an image (in pixels).
+          type: integer
+      required:
+        - height
+        - resource_url
+        - type
+        - uri
+        - uri150
+        - width
     Service:
       description: A type that encapsulates any available information about the service.
       type: object
@@ -306,7 +459,24 @@ components:
           type: string
       required: 
         - message
+  parameters:
+    ArtistId:
+      name: artist_id
+      description: An identifier of an artist.
+      in: path
+      required: true
+      schema:
+        type: integer
+      example: 108713
   responses:
+    NotFound:
+      description: A requested resource cannot be found.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ServiceError'
+          example:
+            message: Resource not found.
     Unavailable:
       description: The service is currently unavailable to handle requests.
       content: