rock-n-code/amiibo-service
1
0
Fork 0
Code Issues Pull Requests Actions Releases 15 Activity

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

Browse Source
This commit is contained in:
Javier Cicchelli
2025-10-15 00:24:01 +02:00
parent 972c2f4487
commit 5521e29599
1 changed files with 116 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/AmiiboService/openapi.yaml
+116 -116
View File
@@ -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: