From 739182a7aee23117e21264127332ae7504b25616 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 14 Oct 2025 23:42:11 +0200
Subject: [PATCH] Improved the definition of the GET /gameseries endpoint for
 the OpenAPI specification document in the library target.

---
 Sources/AmiiboService/openapi.yaml | 61 +++++++++++++++++++++++-------
 1 file changed, 48 insertions(+), 13 deletions(-)

diff --git a/Sources/AmiiboService/openapi.yaml b/Sources/AmiiboService/openapi.yaml
index f0c1a60..cb61bcb 100644
--- a/Sources/AmiiboService/openapi.yaml
+++ b/Sources/AmiiboService/openapi.yaml
@@ -189,10 +189,14 @@ paths:
           description: Service is not available.
   /gameseries:
     get:
-      description: Gets a list of all the game series available in the database.
-      operationId: getGameSeries
       tags:
         - Game
+      summary: Get the game series.
+      description: |
+        Gets a list of all the Game series available in the database.
+
+        Please refer to [the documentation of the endpoint](https://www.amiiboapi.com/docs/#gameSeries) for further information.
+      operationId: getGameSeries
       parameters:
         - $ref: '#/components/parameters/Key'
           description: A key of a game series to include in the response.
@@ -200,11 +204,15 @@ paths:
           description: A name of a game series to include in the response.
       responses:
         '200':
-          $ref: '#/components/responses/SuccessTuple'
+          description: Successful response returning an object that contains one or more game series.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GameSeriesWrapper'
         '400':
-          description: A game series bad request.
+          $ref: '#/components/responses/BadRequest'
         '404':
-          description: A game series not found.
+          $ref: '#/components/responses/NotFound'
         '500':
           description: Service is not available.
   /type:
@@ -213,7 +221,7 @@ paths:
         - Amiibo
       summary: Get the amiibo types.
       description: |
-        Gets a list of all the Amiibo types available in the database.
+        Gets a list of all the amiibo types available in the database.
 
         Please refer to [the documentation of the endpoint](https://www.amiiboapi.com/docs/#type) for further information.
       operationId: getAmiiboTypes
@@ -224,7 +232,7 @@ paths:
           description: A name of an amiibo type to include in the response.
       responses:
         '200':
-          description: Successful response returning an object that contains one or more Amiibo types.
+          description: Successful response returning an object that contains one or more amiibo types.
           content:
             application/json:
               schema:
@@ -397,15 +405,15 @@ components:
           type: string
           format: date-time
     AmiiboType:
-      description: A type that represents an Amiibo type.
+      description: A type that represents an amiibo type.
       allOf:
         - $ref: '#/components/schemas/Tuple'
         - type: object
           properties:
             key:
-              description: A key of an Amiibo type.
+              description: A key of an amiibo type.
             name: 
-              description: A name of an Amiibo type.
+              description: A name of an amiibo type.
     AmiiboUsage:
       description: A type that represents a use of an Amiibo in a game.
       type: object
@@ -419,6 +427,16 @@ components:
       required:
         - Usage
         - write
+    GameSeries:
+      description: A type that represents a game series.
+      allOf:
+        - $ref: '#/components/schemas/Tuple'
+        - type: object
+          properties:
+            key:
+              description: A key of a game series.
+            name: 
+              description: A name of a game series.
     LastUpdated:
       description: A type that informs when the data in the service was last updated.
       type: object
@@ -462,10 +480,16 @@ components:
         description: A list if `Amiibo` instance.
         $ref: '#/components/schemas/Amiibo'
     AmiiboTypeList:
-      description: A type that represents a list of Amiibo types.
+      description: A type that represents a list of amiibo types.
       type: array
       items:
         $ref: '#/components/schemas/AmiiboType'
+    GameSeriesList:
+      description: A type that represents a list of game series.
+      type: array
+      items:
+        $ref: '#/components/schemas/GameSeries'
+# Wrapper Entities
       type: object
       properties:
         amiibo: 
@@ -476,16 +500,27 @@ components:
       required:
         - amiibo
     AmiiboTypeWrapper:
-      description: A type that wraps either one or a list of Amiibo types.
+      description: A type that wraps either one or a list of amiibo types.
       type: object
       properties:
         amiibo: 
-          description: A container that have one or more Amiibo types.
+          description: A container that have one or more amiibo types.
           oneOf:
             - $ref: '#/components/schemas/AmiiboType'
             - $ref: '#/components/schemas/AmiiboTypeList'
       required: 
         - amiibo
+    GameSeriesWrapper:
+      description: A type that wraps either one or a list of game series.
+      type: object
+      properties:
+        amiibo: 
+          description: A container that have one or more game series.
+          oneOf:
+            - $ref: '#/components/schemas/GameSeries'
+            - $ref: '#/components/schemas/GameSeriesList'
+      required: 
+        - amiibo
 # Error Entities
     ServiceError:
       description: A type that represents an error provided by the service.