rock-n-code/discogs-service
1
0
Fork 0
Code Pull Requests Releases 8 Activity

Implemented the GET /database/search endpoint for the Open API specification documentation in the library target.

Browse Source
This commit is contained in:
Javier Cicchelli
2025-10-10 01:28:22 +02:00
parent 5f271b2818
commit fd7504e281
1 changed files with 466 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sources/DiscogsService/openapi.yaml
+466 -156
View File
@@ -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: <https://api.discogs.com/artists/1/releases?page=2&per_page=75>; rel="next", <https://api.discogs.com/artists/1/releases?page=30&per_page=75>; 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: <https://api.discogs.com/artists/1/releases?page=2&per_page=75>; rel="next", <https://api.discogs.com/artists/1/releases?page=30&per_page=75>; 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