Improved the definition of the GET /amiibo endpoint for the OpenAPI specification document in the library target.

Sources/AmiiboService/openapi.yaml

@@ -58,95 +58,39 @@ externalDocs:
 paths:
   /amiibo:
     get:
-      summary: Get a list of Amiibo items.
+      summary: Get a list of amiibos.
-      description: Get a list of all the Amiibo items available in the database.
+      description: |
+        Get a list of all the Amiibo items available in the database.
+
+        Please refer to [the documentation of the endpoint](https://www.amiiboapi.com/docs/#amiibo) for further information.
       operationId: getAmiibos
       tags:
         - Amiibo
+      parameters:
+        - $ref: '#/components/parameters/Identifier'
+        - $ref: '#/components/parameters/IdentifierHead'
+        - $ref: '#/components/parameters/IdentifierTail'
+        - $ref: '#/components/parameters/Name'
+          description: A name of an amiibo to include in the response.
+        - $ref: '#/components/parameters/AmiiboType'
+        - $ref: '#/components/parameters/AmiiboSeries'
+        - $ref: '#/components/parameters/GameCharacter'
+        - $ref: '#/components/parameters/GameSeries'
+        - $ref: '#/components/parameters/ShowGames'
+        - $ref: '#/components/parameters/ShowUsage'
       responses:
         '200':
-          description: Response that retuns a decodable JSON object wrapping a list of Amiibo items.
+          description: Successful response returning an object that contains none, one or more amiibos.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AmiiboWrapper'
         '400':
-          description: An amiibo bad request.
+          $ref: '#/components/responses/BadRequest'
         '404':
-          description: An amiibo not found.
+          $ref: '#/components/responses/NotFound'
         '500':
           description: Service is not available.
-      parameters:
-        - name: amiiboSeries
-          in: query
-          description: An identifier or name of an Amiibo to filter the response.
-          required: false
-          schema:
-            type: string
-          style: form
-        - name: character
-          in: query
-          description: An identifier or name of a game character to filter the response.
-          required: false
-          schema:
-            type: string
-          style: form
-        - name: gameseries
-          in: query
-          description: An identifier or name of a game series to filter the response.
-          required: false
-          schema:
-            type: string
-          style: form
-        - name: head
-          in: query
-          description: A last part of an identifier to filter the response.
-          required: false
-          schema: 
-            type: string
-          style: form
-        - name: id
-          in: query
-          description: An identifier of an Amiibo to filter the response.
-          required: false
-          schema:
-            type: string
-          style: form
-        - name: name
-          in: query
-          description: A name of an Amiibo to filter the response.
-          required: false
-          schema:
-            type: string
-          style: form
-        - name: showgames
-          in: query
-          description: A flag that indicates whether to include information about related games.
-          required: false
-          schema:
-            type: boolean
-          style: form
-        - name: showusage
-          in: query
-          description: A flag that indicates whether to include information about Amiibo usage in related games.
-          required: false
-          schema:
-            type: boolean
-          style: form
-        - name: tail
-          in: query
-          description: A first part of an identifier to filter the response.
-          required: false
-          schema:
-            type: string
-          style: form
-        - name: type
-          in: query
-          description: An identifier or a name of an Amiibo type to filter the response.
-          required: false
-          schema:
-            type: string
-          style: form
   /amiiboseries:
     get:
       tags:
@@ -280,6 +224,58 @@ paths:
           description: Service is not available.
 components:
   parameters:
+    AmiiboSeries:
+      description: An identifier or name of an amiibo series to include in the response
+      name: amiiboSeries
+      in: query
+      required: false
+      schema:
+        type: string
+    AmiiboType:
+      description: An identifier or a name of an amiibo type to inclulde in the response.
+      name: type
+      in: query
+      required: false
+      schema:
+        type: string
+    GameCharacter:
+      description: An identifier or name of a game character to include in the response.
+      name: character
+      in: query
+      required: false
+      schema:
+        type: string
+    GameSeries:
+      description: An identifier or name of a game series to include in the response.
+      name: gameseries
+      in: query
+      required: false
+      schema:
+        type: string
+    Identifier:
+      description: An identifier of an amiibo to include in the response.
+      name: id
+      in: query
+      required: false
+      schema:
+        type: string
+        maxLength: 18
+    IdentifierHead:
+      description: A first part for an identifier of an amiibo to include the response.
+      name: head
+      in: query
+      required: false
+      schema: 
+        type: string
+        maxLength: 10
+    IdentifierTail:
+      description: A last part for an identifier of an amiibo to include the response.
+      name: tail
+      in: query
+      required: false
+      schema: 
+        type: string
+        maxLength: 10
     Key:
       description: A key of a type to include in the response.
       name: key
@@ -294,6 +290,20 @@ components:
       required: false
       schema:
         type: string
+    ShowGames:
+      description: A flag that indicates whether to include information about related games.
+      name: showgames
+      in: query
+      required: false
+      schema:
+        type: boolean
+    ShowUsage:
+      description: A flag that indicates whether to include information about amiibo usages in related games.
+      name: showusage
+      in: query
+      required: false
+      schema:
+        type: boolean
   responses:
     BadRequest:
       description: One or more incorrect parameters have been sent.
@@ -310,59 +320,62 @@ components:
   schemas:
 # Core Entities
     Amiibo:
-      description: A type that contains all the information about an Amiibo.
+      description: A type that represents an amiibo.
       type: object
       properties:
         amiiboSeries:
-          description: A name of the series the Amiibo belongs to.
+          description: A name of a series an amiibo belongs to.
           type: string
         character:
           description: |
-            A name of a character of An Amiibo.
+            A name of a character of an amiibo.
             
             Multiple character have different amiibo design.
           type: string
         gameSeries:
-          description: A name of the game series the Amiibo belongs to.
+          description: A name of a game series an amiibo belongs to.
           type: string
         games3DS:
-          description: A list of 3DS games an Amiibo could be used in, if any.
+          description: A list of 3DS games an amiibo could be used in, if any.
           type: array
           items:
             $ref: '#/components/schemas/AmiiboGame'
         gamesSwitch:
-          description: A list of Switch games an Amiibo could be used in, if any.
+          description: A list of Switch games an amiibo could be used in, if any.
           type: array
           items:
             $ref: '#/components/schemas/AmiiboGame'
         gamesWiiU:
-          description: A list of Wii U games an Amiibo could be used in, if any.
+          description: A list of Wii U games an amiibo could be used in, if any.
           type: array
           items:
             $ref: '#/components/schemas/AmiiboGame'
         head:
           description: |
-            The first 8 characters of the hexadecimal value that identifies an Amiibo.
+            The first 8 characters of the hexadecimal value that identifies an amiibo.
 
             The positions 0 to 7 of the hexadecimal string.
           type: string
+          maxLength: 8
         image:
-          description: An image URL related to an Amiibo.
+          description: An image URL related to an amiibo.
           type: string
+          format: uri
         name:
           description: A name of an Amiibo.
           type: string
         release:
-          description: A type that contains the release dates of an Amiibo, if any.
+          description: A type that contains the release dates of an amiibo, if any.
           $ref: '#/components/schemas/AmiiboRelease'
         tail:
           description: |
-            The last 8 characters of the hexadecimal value that identifies an Amiibo.
+            The last 8 characters of the hexadecimal value that identifies an amiibo.
 
             The positions 8 to 15 of the hexadecimal string.
           type: string
+          maxLength: 8
         type:
-          description: A name for the type an Amiibo belongs to.
+          description: A name for the type an amiibo belongs to.
           type: string
       required:
         - amiiboSeries
@@ -375,33 +388,27 @@ components:
         - tail
         - type
     AmiiboGame:
-      description: A type that represents a game in which an Amiibo is related to.
+      description: A type that represents a game in which an amiibo is related to.
       type: object
       properties:
         amiiboUsage:
-          description: A list of available usages an Amiibo have in a game, if any.
+          description: A list of available usages an amiibo have in a game, if any.
           type: array
           items:
             $ref: '#/components/schemas/AmiiboUsage'
         gameID:
-          description: A list of identifiers of a game an Amiibo is related to.
+          description: A list of identifiers of a game an amiibo is related to.
           type: array
           items:
             type: string
         gameName:
-          description: A name of a game an Amiibo is related to.
+          description: A name of a game an amiibo is related to.
           type: string
       required:
         - gameID
         - gameName
-    AmiiboList:
-      description: A type that contains a list of `Amiibo` instances.
-      type: array
-      items:
-        description: A list if `Amiibo` instance.
-        $ref: '#/components/schemas/Amiibo'
     AmiiboRelease:
-      description: A type that contains the release dates of an Amiibo throughout the world.
+      description: A type that contains the release dates of an amiibo throughout the world.
       type: object
       properties:
         au:
@@ -441,14 +448,14 @@ components:
             name: 
               description: A name of an amiibo type.
     AmiiboUsage:
-      description: A type that represents a use of an Amiibo in a game.
+      description: A type that represents a use of an amiibo in a game.
       type: object
       properties:
         Usage:
-          description: An explanation of the usage of an Amiibo in a game.
+          description: An explanation of the usage of an amiibo in a game.
           type: string
         write:
-          description: A flag that indicates whether the data in an Amiibo is writable or not.
+          description: A flag that indicates whether the data in an amiibo is writable or not.
           type: boolean
       required:
         - Usage
@@ -483,18 +490,6 @@ components:
           format: date-time
       required:
         - lastUpdated
-# Wrapper Entities
-    AmiiboWrapper:
-      description: A type that contains either one or multiple `Amiibo` instances.
-      type: object
-      properties:
-        amiibo: 
-          description: A property that contains one or multiple `Amiibo` instances.
-          oneOf:
-            - $ref: '#/components/schemas/Amiibo'
-            - $ref: '#/components/schemas/AmiiboList'
-      required:
-        - amiibo
     Tuple:
       description: |
         A type that is conformed only by the `key` and `name` properties.
@@ -511,9 +506,11 @@ components:
       required:
         - key
         - name
+# List Entities
+    AmiiboList:
+      description: A type that contains a list of amiibos.
       type: array
       items:
-        description: A list if `Amiibo` instance.
         $ref: '#/components/schemas/Amiibo'
     AmiiboSeriesList:
       description: A type that represents a list of amiibo series.
@@ -536,11 +533,14 @@ components:
       items:
         $ref: '#/components/schemas/GameSeries'
 # Wrapper Entities
+    AmiiboWrapper:
+      description: A type that wraps either none, one or a list of amiibos.
       type: object
       properties:
         amiibo: 
-          description: A property that contains one or multiple `Amiibo` instances.
+          description: A container that have zero, one or more amiibos.
           oneOf:
+            - type: 'null'
             - $ref: '#/components/schemas/Amiibo'
             - $ref: '#/components/schemas/AmiiboList'
       required: