From fd7504e281e2313590d7fbff159385e8dbf66037 Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Fri, 10 Oct 2025 01:28:22 +0200 Subject: [PATCH] Implemented the GET /database/search endpoint for the Open API specification documentation in the library target. --- Sources/DiscogsService/openapi.yaml | 622 +++++++++++++++++++++------- 1 file changed, 466 insertions(+), 156 deletions(-) diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml index 4066b9fbd..4bae986e4 100644 --- a/Sources/DiscogsService/openapi.yaml +++ b/Sources/DiscogsService/openapi.yaml @@ -503,10 +503,324 @@ paths: properties: is_offensive: type: boolean - required: true + required: + - is_offensive '404': $ref: '#/components/responses/NotFound' + /database/search: + get: + tags: + - Database + summary: Search any information from the database. + description: | + Issue a search query to the Discogs database. + + This endpoint supports pagination and also, it requires authentication. + operationId: searchDatabase + parameters: + - name: query + description: A query to search for. + in: query + schema: + type: string + - name: type + description: A type of resource to search for. + in: query + schema: + type: string + enum: + - release + - master + - artist + - label + - name: title + description: | + A title to search for. + + This parameter can be combined with the `name` query parameter. + in: query + schema: + type: string + - name: release_title + description: A release title to search for. + in: query + schema: + type: string + - name: credit + in: query + description: Some credits to search for. + schema: + type: string + - name: artist + description: An artist name to search for. + in: query + schema: + type: string + - name: anv + description: A ANV (Artist Name Variation) to search for. + in: query + schema: + type: string + - name: label + description: A label name to search for. + in: query + schema: + type: string + - name: genre + description: A music genre to search for. + in: query + schema: + type: string + - name: style + description: A musical style to search for. + in: query + schema: + type: string + - name: country + description: A country to search for. + in: query + schema: + type: string + - name: year + description: A release year to search for. + in: query + schema: + type: string + - name: format + description: A release format to search for. + in: query + schema: + type: string + - name: catno + description: A catalogg number to search for. + in: query + schema: + type: string + - name: barcode + description: A barcode number to search for. + in: query + schema: + type: string + - name: track + description: A track title to search for. + in: query + schema: + type: string + - name: submitter + description: A username of a submitter to search for. + in: query + schema: + type: string + - name: contributor + description: A username of a contributor to search for. + in: query + schema: + type: string + - $ref: '#/components/parameters/Page' + - $ref: '#/components/parameters/PerPage' + security: + - Token: [] + - KeySecret: [] + - OAuth: [] + responses: + '200': + description: Successfully retrieved search results. + headers: + Link: + $ref: '#/components/headers/Link' + content: + application/json: + schema: + type: object + properties: + pagination: + $ref: '#/components/schemas/Pagination' + results: + description: A list of artist, label, master and/or release search results. + type: array + items: + oneOf: + - $ref: '#/components/schemas/ReleaseResult' + - $ref: '#/components/schemas/MasterResult' + - $ref: '#/components/schemas/ArtistResult' + - $ref: '#/components/schemas/LabelResult' + '401': + $ref: '#/components/responses/Unauthorized' + '500': + $ref: '#/components/responses/InternalError' components: + headers: + Link: + description: | + Contains URLs for pagination, compliant with RFC 5988. + + It provides `first`, `prev`, `next`, and `last` links where applicable. + schema: + type: string + example: ; rel="next", ; rel="last" + parameters: + ArtistId: + name: artist_id + description: An identifier of an artist. + in: path + required: true + schema: + type: integer + example: 108713 + ArtistReleasesSort: + description: A value to sort the releases of an artist by. + name: sort + in: query + required: false + schema: + type: string + enum: + - year + - title + - format + Country: + description: A filter by country. + name: country + in: query + schema: + type: string + Currency: + description: | + A currency code in the marketplace. + + Defaults to the authenticated users currency. + name: curr_abbr + in: query + schema: + $ref: '#/components/schemas/Currency' + Format: + description: A filter by format. + name: format + in: query + schema: + type: string + Label: + description: A filter by label. + name: label + in: query + schema: + type: string + LabelId: + description: An identifier of a label. + name: label_id + in: path + 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 + MasterVersionsSort: + description: A value to sort the master versions by. + name: sort + in: query + schema: + type: string + enum: + - released + - title + - format + - label + - catno + - country + Page: + description: A number of page of results to return. + name: page + in: query + required: false + schema: + type: integer + minimum: 1 + PerPage: + description: A number of items to return per page. + name: per_page + in: query + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + Released: + description: A filter by release year. + name: released + in: query + schema: + type: string + ReleaseId: + description: An identifier of a release. + name: release_id + in: path + required: true + schema: + type: integer + example: 249504 + SortOrder: + description: The order to sort the results. + name: sort_order + in: query + required: false + schema: + type: string + enum: + - asc + - desc + Username: + description: A username of a user. + name: username + in: path + required: true + schema: + type: string + example: memory + responses: + InternalError: + description: An Internal Server error was encountered. + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceError' + examples: + Timeout: + value: + message: Query time exceeded. Please try a simpler query. + Malformed: + value: + message: An internal server error occurred. (Malformed query?) + NotFound: + description: A requested resource cannot be found. + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceError' + example: + message: Resource not found. + Unauthorized: + description: A requested resource cannot be accessed. + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceError' + example: + message: You must authenticate to access this resource. + Unavailable: + description: The service is currently unavailable to handle requests. + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceError' + example: + message: Server is currently unavailable. schemas: Artist: description: A type that represents an artist or a group. @@ -657,6 +971,14 @@ components: - title - thumb - type + ArtistResult: + description: A type that represents an artist search result. + allOf: + - $ref: '#/components/schemas/SearchResult' + - type: object + properties: + type: + enum: [artist] Community: description: A type that represents a community of users, in relationship to a release. type: object @@ -684,12 +1006,7 @@ components: description: An explanation for the stat status of a community. type: string required: - - contributors - - data_quality - have - - rating - - status - - submitter - want Currency: description: A list of currency codes defined in the marketplace. @@ -889,6 +1206,14 @@ components: - title - thumb - year + LabelResult: + description: A type that represents a label search result. + allOf: + - $ref: '#/components/schemas/SearchResult' + - type: object + properties: + type: + enum: [label] Master: description: A type that represents a set of similar releases. type: object @@ -907,6 +1232,17 @@ components: description: A URL link to the versions of this master. type: string format: uri + MasterResult: + description: A type that represents a master search result. + allOf: + - $ref: '#/components/schemas/SearchResult' + - type: object + properties: + type: + enum: [master] + main_release: + description: An identifier of a main release for a master. + type: integer Pagination: description: A type that provides details about a paginated result. type: object @@ -980,7 +1316,7 @@ components: format: uri readOnly: true uri: - description: A URI representation of a release. + description: A URI representation of a release. type: string format: uri readOnly: true @@ -1158,6 +1494,14 @@ components: - rating - release_id - username + ReleaseResult: + description: A type that represents a release search result. + allOf: + - $ref: '#/components/schemas/SearchResult' + - type: object + properties: + type: + enum: [release] ReleaseStats: description: A type that represents the statistics of a release. type: object @@ -1244,6 +1588,91 @@ components: - status - thumb - title + SearchResult: + description: A type that represents a search result. + type: object + properties: + id: + description: An identifier of a result. + type: integer + readOnly: true + type: + description: A type of a result. + type: string + enum: [''] + title: + description: A title of a result + type: string + thumb: + description: A URL link to a thumbnail of a result. + type: string + format: uri + cover_image: + description: A URL link to a cover image of a result. + type: string + format: uri + resource_url: + description: A URI resource of a result. + type: string + format: uri + readOnly: true + uri: + description: A URI representation of a release. + type: string + readOnly: true + country: + description: A country of a result. + type: string + year: + description: A number of year of a result. + type: string + community: + $ref: '#/components/schemas/Community' + format: + description: A list of formats associated with a result. + type: array + items: + type: string + label: + description: A list of labels associated with a result. + type: array + items: + type: string + catno: + description: A category number of a result. + type: string + genre: + description: A list of music genres associated with a result. + type: array + items: + type: string + style: + description: A list of music styles associated with a result. + type: array + items: + type: string + barcode: + description: A list of barcode numbers associated with a result. + type: array + items: + type: string + required: + - barcode + - catno + - community + - country + - cover_image + - format + - genre + - id + - label + - resource_url + - style + - thumb + - title + - type + - uri + - year Service: description: A type that encapsulates any available information about the service. type: object @@ -1355,154 +1784,35 @@ components: - embed - title - uri - parameters: - ArtistId: - name: artist_id - description: An identifier of an artist. - in: path - required: true - schema: - type: integer - example: 108713 - ArtistReleasesSort: - description: A value to sort the releases of an artist by. - name: sort - in: query - required: false - schema: - type: string - enum: - - year - - title - - format - Country: - description: A filter by country. - name: country - in: query - schema: - type: string - Currency: + securitySchemes: + KeySecret: description: | - A currency code in the marketplace. - - Defaults to the authenticated users currency. - name: curr_abbr - in: query - schema: - $ref: '#/components/schemas/Currency' - Format: - description: A filter by format. - name: format - in: query - schema: - type: string - MasterVersionsSort: - description: A value to sort the master versions by. - name: sort - in: query - schema: - type: string - enum: - - released - - title - - format - - label - - catno - - country - Label: - description: A filter by label. - name: label - in: query - schema: - type: string - LabelId: - description: An identifier of a label. - name: label_id - in: path - 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 - in: query - required: false - schema: - type: integer - minimum: 1 - PerPage: - description: A number of items to return per page. - name: per_page - in: query - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - Released: - description: A filter by release year. - name: released - in: query - schema: - type: string - ReleaseId: - description: An identifier of a release. - name: release_id - in: path - required: true - schema: - type: integer - example: 249504 - SortOrder: - description: The order to sort the results. - name: sort_order - in: query - required: false - schema: - type: string - enum: - - asc - - desc - Username: - description: A username of a user. - name: username - in: path - required: true - schema: - type: string - example: memory - headers: - Link: - description: | - Contains URLs for pagination, compliant with RFC 5988. + Discogs authentication using a key/secret pair. - It provides `first`, `prev`, `next`, and `last` links where applicable. - schema: - type: string - example: ; rel="next", ; rel="last" - responses: - NotFound: - description: A requested resource cannot be found. - content: - application/json: - schema: - $ref: '#/components/schemas/ServiceError' - example: - message: Resource not found. - Unavailable: - description: The service is currently unavailable to handle requests. - content: - application/json: - schema: - $ref: '#/components/schemas/ServiceError' - example: - message: Server is currently unavailable. + The `Authorization` header should be in format: + ``` + Discogs key={A_CONSUMER_KEY}, secret={A_CONSUMER_SECRET} + ``` + type: apiKey + name: Authorization + in: header + OAuth: + description: | + OAuth 1.0a flow for third-party applications. + + This is a placeholder as OpenAPI 3.1 does not directly support OAuth 1.0a. + + The `Authorization` header should be constructed according to OAuth 1.0a specs, for example: `OAuth oauth_consumer_key="...", oauth_nonce="...", ...` + type: http + scheme: oauth + Token: + description: | + Discogs authentication using a personal access token. + + The `Authorization` header should be in format: + ``` + Discogs token={YOUR_PERSONAL_ACCESS_TOKEN} + ``` + type: apiKey + name: Authorization + in: header