From c55b6e467fc5d87c136ddcb81c7c64a9799afa6f Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Tue, 7 Oct 2025 19:35:59 +0200 Subject: [PATCH] Added descriptions to the components types for the OpenAPI specification document in the library target. --- Sources/AmiiboService/openapi.yaml | 82 ++++++++++++++++++++++++++---- 1 file changed, 73 insertions(+), 9 deletions(-) diff --git a/Sources/AmiiboService/openapi.yaml b/Sources/AmiiboService/openapi.yaml index 12d656e..60b97ae 100644 --- a/Sources/AmiiboService/openapi.yaml +++ b/Sources/AmiiboService/openapi.yaml @@ -77,56 +77,70 @@ paths: parameters: - name: amiiboSeries in: query - description: The Amiibo series identifier or name to filter the response. + description: An identifier or name of an Amiibo to filter the response. required: false schema: type: string style: form - name: character in: query - description: The game character identifier or name to filter the response. + 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: The game series identifier or name to filter the response. + 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: The Amiibo identifier to filter the response. + description: An identifier of an Amiibo to filter the response. required: false schema: type: string style: form - name: name in: query - description: The Amiibo name to filter the response. + description: A name of an Amiibo to filter the response. required: false schema: type: string style: form - name: showgames in: query - description: The flag that indicates whether to include information about related games. + description: A flag that indicates whether to include information about related games. required: false schema: type: boolean style: form - name: showusage in: query - description: The flag that indicates whether to include information about Amiibo usage in related games. + 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: The Amiibo type to filter the response. + description: An identifier or a name of an Amiibo type to filter the response. required: false schema: type: string @@ -302,37 +316,59 @@ components: schemas: # Core Entities Amiibo: + description: A type that contains all the information about an Amiibo. type: object properties: amiiboSeries: + description: A name of the series the Amiibo belongs to. type: string character: + description: | + 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. type: string games3DS: + 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. type: array items: $ref: '#/components/schemas/AmiiboGame' gamesWiiU: + 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 positions 0 to 7 of the hexadecimal string. type: string image: + description: An image URL related to an Amiibo. type: string name: + description: A name of an Amiibo. type: string release: + 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 positions 8 to 15 of the hexadecimal string. type: string type: + description: A name for the type an Amiibo belongs to. type: string required: - amiiboSeries @@ -345,86 +381,114 @@ components: - tail - type AmiiboGame: + 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. type: array items: $ref: '#/components/schemas/AmiiboUsage' gameID: + 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. 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. type: object properties: au: + description: A release date for Australia, if any. type: string format: date-time eu: + description: A release date for Europe, if any. type: string format: date-time jp: + description: A release date for Japan, if any. type: string format: date-time na: + description: A release date for North America, if any. type: string format: date-time AmiiboUsage: + 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. type: string write: + description: A flag that indicates whether the data in an Amiibo is writable or not. type: boolean required: - Usage - write LastUpdated: + description: A type that informs when the data in the service was last updated. type: object properties: lastUpdated: + description: The date and time when the data in the database was last updated. type: string format: date-time required: - lastUpdated # Wrapper Entities AmiiboWrapper: + description: A type that contains either one or multiple `Amiibo` instances. type: object properties: - amiibo: + 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. + + This type represents either `AmiiboSeries`, `AmiiboType`, `GameCharacter`, and `GameSeries` types. type: object properties: key: + description: A key assigned to a tuple. type: string name: + description: A name assigned to a tuple. type: string 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. type: object properties: amiibo: + description: A property that contains one or multiple `Tuple` instances. oneOf: - $ref: '#/components/schemas/Tuple' - $ref: '#/components/schemas/TupleList'