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

---
 Sources/AmiiboService/openapi.yaml | 86 +++++++++++++++++++++++-------
 1 file changed, 68 insertions(+), 18 deletions(-)

diff --git a/Sources/AmiiboService/openapi.yaml b/Sources/AmiiboService/openapi.yaml
index 11df1ac..f0c1a60 100644
--- a/Sources/AmiiboService/openapi.yaml
+++ b/Sources/AmiiboService/openapi.yaml
@@ -209,10 +209,14 @@ paths:
           description: Service is not available.
   /type:
     get:
-      description: Gets a list of all the Amiibo types available in the database.
-      operationId: getAmiiboTypes
       tags:
         - Amiibo
+      summary: Get the amiibo types.
+      description: |
+        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
       parameters:
         - $ref: '#/components/parameters/Key'
           description: A key of an amiibo type to include in the response.
@@ -220,11 +224,15 @@ paths:
           description: A name of an amiibo type to include in the response.
       responses:
         '200':
-          $ref: '#/components/responses/SuccessTuple'
+          description: Successful response returning an object that contains one or more Amiibo types.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AmiiboTypeWrapper'
         '400':
-          description: An amiibo type bad request.
+          $ref: '#/components/responses/BadRequest'
         '404':
-          description: An amiibo type not found.
+          $ref: '#/components/responses/NotFound'
         '500':
           description: Service is not available.
   /lastupdated:
@@ -263,12 +271,18 @@ components:
       schema:
         type: string
   responses:
-    SuccessTuple:
-      description: Response that returns a JSON object containing requested `Tuple` data from a resource.
+    BadRequest:
+      description: One or more incorrect parameters have been sent.
       content: 
         application/json:
           schema:
-            $ref: '#/components/schemas/TupleWrapper'
+            $ref: '#/components/schemas/ServiceError'
+    NotFound:
+      description: No resource has been found.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ServiceError'
   schemas:
 # Core Entities
     Amiibo:
@@ -382,6 +396,16 @@ components:
           description: A release date for North America, if any.
           type: string
           format: date-time
+    AmiiboType:
+      description: A type that represents an Amiibo type.
+      allOf:
+        - $ref: '#/components/schemas/Tuple'
+        - type: object
+          properties:
+            key:
+              description: A key of an Amiibo type.
+            name: 
+              description: A name of an Amiibo type.
     AmiiboUsage:
       description: A type that represents a use of an Amiibo in a game.
       type: object
@@ -433,20 +457,46 @@ components:
       required:
         - key
         - name
-    TupleList:
-      description: A type that represents a list of key/value tuples.
       type: array
       items:
-        description: A property that can contains multiple `Tuple` instances.
-        $ref: '#/components/schemas/Tuple'
-    TupleWrapper:
-      description: A type that contains either one or multiple `Tuple` instances.
+        description: A list if `Amiibo` instance.
+        $ref: '#/components/schemas/Amiibo'
+    AmiiboTypeList:
+      description: A type that represents a list of Amiibo types.
+      type: array
+      items:
+        $ref: '#/components/schemas/AmiiboType'
       type: object
       properties:
-        amiibo:
-          description: A property that contains one or multiple `Tuple` instances.
+        amiibo: 
+          description: A property that contains one or multiple `Amiibo` instances.
           oneOf:
-            - $ref: '#/components/schemas/Tuple'
-            - $ref: '#/components/schemas/TupleList'
+            - $ref: '#/components/schemas/Amiibo'
+            - $ref: '#/components/schemas/AmiiboList'
       required:
         - amiibo
+    AmiiboTypeWrapper:
+      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.
+          oneOf:
+            - $ref: '#/components/schemas/AmiiboType'
+            - $ref: '#/components/schemas/AmiiboTypeList'
+      required: 
+        - amiibo
+# Error Entities
+    ServiceError:
+      description: A type that represents an error provided by the service.
+      type: object
+      properties:
+        code:
+          description: A number of an error code.
+          type: integer
+        error:
+          description: An explanation of an error.
+          type: string
+      required:
+        - code
+        - error
\ No newline at end of file