From 5521e295999bc398b177298c80cf0d95903543e7 Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Wed, 15 Oct 2025 00:24:01 +0200 Subject: [PATCH] Improved the definition of the GET /amiibo endpoint for the OpenAPI specification document in the library target. --- Sources/AmiiboService/openapi.yaml | 232 ++++++++++++++--------------- 1 file changed, 116 insertions(+), 116 deletions(-) diff --git a/Sources/AmiiboService/openapi.yaml b/Sources/AmiiboService/openapi.yaml index e646fd1..318c38a 100644 --- a/Sources/AmiiboService/openapi.yaml +++ b/Sources/AmiiboService/openapi.yaml @@ -58,95 +58,39 @@ externalDocs: paths: /amiibo: get: - summary: Get a list of Amiibo items. - description: Get a list of all the Amiibo items available in the database. + summary: Get a list of amiibos. + 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: