From 8ea8b082bee768bf37c221b1dcc32ceffef8a54c Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Thu, 9 Oct 2025 15:41:42 +0200 Subject: [PATCH] Implemented the GET /masters/{master-id} endpoint for the Open API specification documentation in the library target. --- Sources/DiscogsService/openapi.yaml | 340 +++++++++++++++++++++++++++- 1 file changed, 338 insertions(+), 2 deletions(-) diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml index 60a8ad373..c45862793 100644 --- a/Sources/DiscogsService/openapi.yaml +++ b/Sources/DiscogsService/openapi.yaml @@ -363,6 +363,27 @@ paths: $ref: '#/components/schemas/LabelRelease' '404': $ref: '#/components/responses/NotFound' + /masters/{master_id}: + get: + tags: + - Database + summary: Get information about a master release. + description: | + Retrieves any available information for a specific master release. + + A master release represents a set of similar releases. + operationId: getMaster + parameters: + - $ref: '#/components/parameters/MasterId' + responses: + '200': + description: Successfully retrieved master release details. + content: + application/json: + schema: + $ref: '#/components/schemas/Master' + '404': + $ref: '#/components/responses/NotFound' components: schemas: Artist: @@ -453,13 +474,12 @@ components: description: TBD type: string role: - description: TBD + description: A role of an artist. type: string tracks: description: TBD type: string required: - - active - id - name - resource_url @@ -515,6 +535,67 @@ components: - title - thumb - type + Community: + description: A type that represents a community of users, in relationship to a release. + type: object + properties: + have: + description: A number of users that have a release. + type: integer + want: + description: A number of users that want a release. + type: integer + rating: + description: A type that represents a community rating of a release. + type: object + properties: + count: + description: A number of ratings given by users of a release. + type: integer + average: + description: An average of the ratings given by users of a release. + type: number + format: float + required: + - average + - count + submitter: + description: A reference of a user that submitted the release into the database. + $ref: '#/components/schemas/UserId' + contributors: + description: A list of references of users that contributed data of a release into the database. + type: array + items: + $ref: '#/components/schemas/UserId' + data_quality: + description: An explanation for the data quality related to a community. + type: string + status: + description: An explanation for the stat status of a community. + type: string + required: + - contributors + - data_quality + - have + - rating + - status + - submitter + - want + Identifier: + description: A type that represents an identifier. + type: object + properties: + type: + description: A type of an identifier. + type: string + value: + description: A value of an identifier, if any. + type: string + description: + description: A description of an identifier, if any. + type: string + required: + - type Image: description: A type that represents an image of a resource. type: object @@ -577,6 +658,7 @@ components: description: A URL to the releases of a label. type: string format: uri + readOnly: true profile: description: A detailed profile of a label, if any. type: string @@ -681,6 +763,24 @@ components: - title - thumb - year + Master: + description: A type that represents a set of similar releases. + type: object + allOf: + - $ref: '#/components/schemas/Release' + - type: object + properties: + main_release: + description: An identifier of the main release for this master. + type: integer + main_release_url: + description: A URL link of the main release for this master. + type: string + format: uri + versions_url: + description: A URL link to the versions of this master. + type: string + format: uri Pagination: description: A type that provides details about a paginated result. type: object @@ -723,6 +823,167 @@ components: - per_page - items - urls + Release: + description: A type that eepresents a particular physical or digital object released by one or more artists. + type: object + properties: + id: + description: An identifier of a release. + type: integer + readOnly: true + title: + description: A title of a release. + type: string + resource_url: + description: A URI resource of a release. + type: string + format: uri + readOnly: true + uri: + description: A URI representation of a release. + type: string + format: uri + readOnly: true + status: + description: A status of a release. + type: string + data_quality: + description: An explanation for the data quality related to a release. + type: string + thumb: + description: A URL link to a thumbnail of a release. + type: string + format: uri + country: + description: A country of a release, if any. + type: string + year: + description: A number of year of a release, if any. + type: integer + notes: + description: Notes of a release, if any. + type: string + released: + description: A release date of a release in a free-text format. + type: string + released_formatted: + description: A released date of a release in formatted text. + type: string + date_added: + description: A date and time of a release being added to the database. + type: string + format: date-time + date_changed: + description: A date and time of a release being updated in the database. + type: string + format: date-time + lowest_price: + description: A decimal number for the lowest price of a release in the marketplace, if any. + type: number + format: float + num_for_sale: + description: A number of items of a release for sale in the marketplace, if any. + type: integer + estimated_weight: + description: An estimated weight of a release, if any. + type: integer + format_quantity: + description: A total number of formats of a release. + type: integer + master_id: + description: An identifier of a master associated with a release, if any. + type: integer + master_url: + description: A URL link to a master associated with a release, if any. + type: string + format: uri + artists: + description: A list of artists associated with a release. + type: array + items: + $ref: '#/components/schemas/ArtistId' + labels: + description: A list of labels associated with a release. + type: array + items: + $ref: '#/components/schemas/LabelId' + extraartists: + description: A list of extra artists associated with a release. + type: array + items: + $ref: '#/components/schemas/ArtistId' + formats: + description: A list of formats of a release. + type: array + items: + $ref: '#/components/schemas/ReleaseFormat' + genres: + description: A list of music genres of a release. + type: array + items: + type: string + styles: + description: A list of musical styles of a release. + type: array + items: + type: string + community: + description: Some community information of a release. + $ref: '#/components/schemas/Community' + companies: + description: A list of companies related to a release. + type: array + items: + $ref: '#/components/schemas/LabelId' + tracklist: + description: A list of tracks of a release. + type: array + items: + $ref: '#/components/schemas/Track' + videos: + description: A list of videos associated with a release. + type: array + items: + $ref: '#/components/schemas/Video' + identifiers: + description: A list of identifiers associated with a release. + type: array + items: + $ref: '#/components/schemas/Identifier' + required: + - artists + - data_quality + - genres + - id + - resource_url + - status + - styles + - title + - tracklist + - uri + - videos + ReleaseFormat: + description: A type that represents a format of a release. + type: object + properties: + name: + description: A name of a format. + type: string + qty: + description: A quantity of a format. + type: string # Note: API returns this as a string + text: + description: An explanation of a format, if any. + type: string + descriptions: + description: A list of descriptions of a format. + type: array + items: + type: string + required: + - name + - qty + - descriptions Service: description: A type that encapsulates any available information about the service. type: object @@ -768,6 +1029,72 @@ components: type: string required: - message + Track: + description: A type that represents a track. + type: object + properties: + position: + description: A position number of a track. + type: string + type_: + description: A type of a track. + type: string + title: + description: A title of a track. + type: string + duration: + description: A duration of a track in number of seconds. + type: string + extraartists: + description: A list of extra artists related to a track. + type: array + items: + $ref: '#/components/schemas/ArtistId' + UserId: + description: A type that references a user. + type: object + properties: + id: + description: An identifier of a user. + type: integer + username: + description: A username of a user. + type: string + resource_url: + description: A URI resource of a user. + type: string + format: uri + required: + - id + - resource_url + - username + Video: + description: A type that represents a video. + type: object + properties: + uri: + description: A URI representation of a video. + type: string + format: uri + readOnly: true + duration: + description: A duration of a video in number of seconds. + type: integer + title: + description: A title of a video. + type: string + description: + description: A description of a video. + type: string + embed: + description: A flag that indicates whether a video is embedded or not. + type: boolean + required: + - description + - duration + - embed + - title + - uri parameters: ArtistId: name: artist_id @@ -795,6 +1122,15 @@ components: required: true schema: type: integer + example: 1 + MasterId: + description: An identifier of a master. + name: master_id + in: path + required: true + schema: + type: integer + example: 1000 Page: description: A number of page of results to return. name: page