From ada7c3b85ec9b6e056292b214ac4a55cabb198e7 Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Wed, 15 Oct 2025 19:23:48 +0200 Subject: [PATCH 1/6] Renamed the "KeySecret" and "Token" security schemas for the Open API specification document in the library target as "ConsumerKeySecret" and "UserToken" respectively. --- Sources/DiscogsService/openapi.yaml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml index 3376537f6..50bbc73dc 100644 --- a/Sources/DiscogsService/openapi.yaml +++ b/Sources/DiscogsService/openapi.yaml @@ -346,8 +346,8 @@ paths: For further details about this process, please refer to the [OAuth flow](https://www.discogs.com/developers#page:authentication,header:authentication-oauth-flow) section in the [Discogs API authentication](https://www.discogs.com/developers#page:authentication) documentation. operationId: getUserIdentity security: - - Token: [] - - KeySecret: [] + - UserToken: [] + - ConsumerKeySecret: [] - OAuth: [] responses: '200': @@ -477,8 +477,8 @@ paths: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' security: - - Token: [] - - KeySecret: [] + - UserToken: [] + - ConsumerKeySecret: [] - OAuth: [] responses: '200': @@ -806,8 +806,8 @@ paths: - $ref: '#/components/parameters/Username' - $ref: '#/components/parameters/Rating' security: - - Token: [] - - KeySecret: [] + - UserToken: [] + - ConsumerKeySecret: [] - OAuth: [] responses: '200': @@ -842,8 +842,8 @@ paths: - $ref: '#/components/parameters/ReleaseId' - $ref: '#/components/parameters/Username' security: - - Token: [] - - KeySecret: [] + - UserToken: [] + - ConsumerKeySecret: [] - OAuth: [] responses: '200': @@ -2113,7 +2113,7 @@ components: - title - uri securitySchemes: - KeySecret: + ConsumerKeySecret: description: | Discogs authentication using a key/secret pair. @@ -2133,7 +2133,7 @@ components: 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: + UserToken: description: | Discogs authentication using a personal access token. -- 2.52.0 From 88d577daca3a53001c539df645af564129c24fe1 Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Wed, 15 Oct 2025 20:46:51 +0200 Subject: [PATCH 2/6] Defined the GET /users/{username} endpoints for the Open API specification document in the library target. --- Sources/DiscogsService/openapi.yaml | 194 ++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml index 50bbc73dc..ee897301b 100644 --- a/Sources/DiscogsService/openapi.yaml +++ b/Sources/DiscogsService/openapi.yaml @@ -896,6 +896,42 @@ paths: - is_offensive '404': $ref: '#/components/responses/NotFound' + /users/{username}: + get: + tags: + - User Identity + summary: Get information about a user. + description: | + Retrieves a user by username. + + In case of being authenticated as the requested user, the `email` property will be visible, and the `num_list` count will also include a user's private lists. + + In case of being authenticated as the requested user, or a user's collection or wantlist is public, the `num_collection` and the `num_wantlist` properties will also be visible. + operationId: getUserProfile + parameters: + - $ref: '#/components/parameters/Username' + security: + - UserToken: [] + - ConsumerKeySecret: [] + - OAuth: [] + responses: + '200': + description: Successfully retrieved profile user information by a given username. + headers: + X-Discogs-RateLimit: + $ref: '#/components/headers/RateLimit' + X-Discogs-RateLimit-Used: + $ref: '#/components/headers/RateLimitUsed' + X-Discogs-RateLimit-Remaining: + $ref: '#/components/headers/RateLimitRemaining' + content: + application/json: + schema: + $ref: '#/components/schemas/UserProfile' + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalError' components: headers: Link: @@ -2085,6 +2121,164 @@ components: consumer_name: description: A name of an application a user utilizes to interacts with the service. type: string + UserProfile: + description: A type that represents a user profile. + allOf: + - $ref: '#/components/schemas/UserId' + - type: object + properties: + name: + description: A name of a user. + type: string + email: + description: An e-mail address of a user, if any. + type: string + format: email + profile: + description: A profile explanation of a user. + type: string + location: + description: A physical location of a user. + type: string + uri: + description: A URL to the resource of a user. + type: string + format: uri + home_page: + description: A URI to the home page of a user. + type: string + format: uri + registered: + description: A date and time a user registered to the service. + type: string + format: date-time + rank: + description: A number of rank of a user. + type: integer + curr_abbr: + description: A code of a currency used by a user in the marketplace. + type: string + minLength: 3 + maxLength: 3 + activated: + description: A flag that indicates whether a user is active or not. + type: boolean + marketplace_suspended: + description: A flag that indicates whether a user is suspended at the marketplace or not. + type: boolean + is_staff: + description: A flag that indicates whether a user is member of the staff at the service or not. + type: boolean + num_collection: + description: A number of items a user have in its collection. + type: integer + num_lists: + description: A number of list a user created. + type: integer + num_pending: + description: A number of items a user have in its pending list. + type: integer + num_for_sale: + description: A number of item a user have for sale in the marketplace. + type: integer + num_wantlist: + description: A number of items a user have in its want list, if any. + type: integer + rating_avg: + description: An average rating to the total of releases a user rated. + type: number + format: float + minimum: 0 + maximum: 5 + releases_contributed: + description: A number of releases that a user contributed information. + type: integer + releases_rated: + description: A number of release that a user rated. + type: integer + buyer_rating: + description: An average rating a user have in the marketplace as a buyer. + type: number + format: float + minimum: 0 + maximum: 100 + buyer_rating_stars: + description: A number of star rating a user have in the marketplace as a buyer. + type: integer + minimum: 0 + maximum: 5 + buyer_num_ratings: + description: A total number of ratings a user have in the marketplace as a buyer. + type: integer + seller_rating: + description: An average rating a user have in the marketplace as a seller. + type: number + format: float + minimum: 0 + maximum: 100 + seller_rating_stars: + description: A number of star rating a user have in the marketplace as a seller. + type: integer + minimum: 0 + maximum: 5 + seller_num_ratings: + description: A total number of ratings a user have in the marketplace as a seller. + type: integer + avatar_url: + description: A URL to the avatar of a user. + type: string + format: uri + banner_url: + description: A URL to th banner of a user. + type: string + format: uri + collection_fields_url: + description: A URL to the collection fields of a user. + type: string + format: uri + collection_folders_url: + description: A URL to the collection forlder of a user. + type: string + format: uri + inventory_url: + description: A URL to the inventory of a user. + type: string + format: uri + wantlist_url: + description: A URI to the want list of a user. + type: string + format: uri + required: + - activated + - avatar_url + - banner_url + - buyer_num_ratings + - buyer_rating + - buyer_rating_stars + - collection_fields_url + - collection_folders_url + - curr_abbr + - home_page + - inventory_url + - is_staff + - location + - marketplace_suspended + - name + - num_collection + - num_lists + - num_for_sale + - num_pending + - profile + - rating_avg + - rank + - registered + - releases_contributed + - releases_rated + - seller_num_ratings + - seller_rating + - seller_rating_stars + - uri + - wantlist_url Video: description: A type that represents a video. type: object -- 2.52.0 From d9f23e29c3f76c738030cc2f750c6d7271aaad13 Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Wed, 15 Oct 2025 21:26:54 +0200 Subject: [PATCH 3/6] Defined the POST /users/{username} endpoints for the Open API specification document in the library target. --- Sources/DiscogsService/openapi.yaml | 93 +++++++++++++++++++++++++---- 1 file changed, 83 insertions(+), 10 deletions(-) diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml index ee897301b..cb82b67ae 100644 --- a/Sources/DiscogsService/openapi.yaml +++ b/Sources/DiscogsService/openapi.yaml @@ -902,7 +902,7 @@ paths: - User Identity summary: Get information about a user. description: | - Retrieves a user by username. + Retrieves a user profile by username. In case of being authenticated as the requested user, the `email` property will be visible, and the `num_list` count will also include a user's private lists. @@ -910,10 +910,6 @@ paths: operationId: getUserProfile parameters: - $ref: '#/components/parameters/Username' - security: - - UserToken: [] - - ConsumerKeySecret: [] - - OAuth: [] responses: '200': description: Successfully retrieved profile user information by a given username. @@ -932,6 +928,46 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' + post: + tags: + - User Identity + summary: Update information about a user. + description: | + Edits some user profile information by username. + + This endpoint requires authentication. + operationId: postUserProfile + parameters: + - $ref: '#/components/parameters/Username' + - $ref: '#/components/parameters/Name' + - $ref: '#/components/parameters/HomePage' + - $ref: '#/components/parameters/Location' + - $ref: '#/components/parameters/Profile' + - $ref: '#/components/parameters/Currency' + security: + - UserToken: [] + - ConsumerKeySecret: [] + - OAuth: [] + responses: + '200': + description: Successfully retrieved an updated profile user information by a given username. + headers: + X-Discogs-RateLimit: + $ref: '#/components/headers/RateLimit' + X-Discogs-RateLimit-Used: + $ref: '#/components/headers/RateLimitUsed' + X-Discogs-RateLimit-Remaining: + $ref: '#/components/headers/RateLimitRemaining' + content: + application/json: + schema: + $ref: '#/components/schemas/UserProfile' + '403': + $ref: '#/components/responses/NotAccessable' + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalError' components: headers: Link: @@ -1038,6 +1074,14 @@ components: in: query schema: type: string + HomePage: + description: A URI to a website of a user. + name: home_page + in: query + schema: + type: string + format: uri + example: https://www.some-home.page Label: description: A filter by label. name: label @@ -1052,6 +1096,13 @@ components: schema: type: integer example: 1 + Location: + description: A geographical location of a user. + name: location + in: query + schema: + type: string + example: Planet Earth MasterId: description: An identifier of a master. name: master_id @@ -1073,6 +1124,13 @@ components: - label - catno - country + Name: + description: A real name of a user. + name: name + in: query + schema: + type: string + example: Some real name Page: description: A number of page of results to return. name: page @@ -1090,6 +1148,13 @@ components: type: integer minimum: 1 maximum: 100 + Profile: + description: A biographical information about a user. + name: profile + in: query + schema: + type: string + example: Some biographical information about a user goes here... Rating: description: A number (between 1 and 5) for a rating of a release. name: rating @@ -1152,6 +1217,14 @@ components: Malformed: value: message: An internal server error occurred. (Malformed query?) + NotAccessable: + description: A requested resource cannot be accessed due to a lack of permission. + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceError' + example: + message: You must have permission to access this resource. NotFound: description: A requested resource cannot be found. content: @@ -1161,7 +1234,7 @@ components: example: message: Resource not found. Unauthorized: - description: A requested resource cannot be accessed. + description: A requested resource cannot be accessed due to a lack of authentication. content: application/json: schema: @@ -2128,24 +2201,24 @@ components: - type: object properties: name: - description: A name of a user. + description: A real name of a user. type: string email: description: An e-mail address of a user, if any. type: string format: email profile: - description: A profile explanation of a user. + description: A biographical information of a user. type: string location: - description: A physical location of a user. + description: A geographical location of a user. type: string uri: description: A URL to the resource of a user. type: string format: uri home_page: - description: A URI to the home page of a user. + description: A URI to a website of a user. type: string format: uri registered: -- 2.52.0 From 8ee9f29f5cbeedbe47aa466b90c2a27723166e3f Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Wed, 15 Oct 2025 22:52:38 +0200 Subject: [PATCH 4/6] Defined the GET /users/{username}/submissions endpoints for the Open API specification document in the library target. --- Sources/DiscogsService/openapi.yaml | 61 +++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 3 deletions(-) diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml index cb82b67ae..ccb2b60e1 100644 --- a/Sources/DiscogsService/openapi.yaml +++ b/Sources/DiscogsService/openapi.yaml @@ -968,6 +968,45 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' + /users/{username}/submissions: + get: + tags: + - User Identity + summary: Get submissions of a user. + description: | + Retrieves all the submissions or edits to releases, labels, and artist done by username. + + This endpoints accepts pagination headers. + operationId: getUserSubmissions + parameters: + - $ref: '#/components/parameters/Username' + responses: + '200': + description: Successfully retrieved items submitted by a user. + headers: + X-Discogs-RateLimit: + $ref: '#/components/headers/RateLimit' + X-Discogs-RateLimit-Used: + $ref: '#/components/headers/RateLimitUsed' + X-Discogs-RateLimit-Remaining: + $ref: '#/components/headers/RateLimitRemaining' + content: + application/json: + schema: + type: object + properties: + pagination: + $ref: '#/components/schemas/Pagination' + submissions: + description: A type that represents all items edited by a user. + $ref: '#/components/schemas/UserItems' + required: + - pagination + - submissions + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalError' components: headers: Link: @@ -1863,9 +1902,7 @@ components: - status - styles - title - - tracklist - uri - - videos ReleaseFormat: description: A type that represents a format of a release. type: object @@ -2182,7 +2219,6 @@ components: type: string format: uri required: - - id - resource_url - username UserIdentity: @@ -2194,6 +2230,25 @@ components: consumer_name: description: A name of an application a user utilizes to interacts with the service. type: string + UserItems: + description: A type that represents all items added and/or edited by a user. + type: object + properties: + artists: + description: A list of artists added and/or edited by a user. + type: array + items: + $ref: '#/components/schemas/Artist' + labels: + description: A list of labels added and/or edited by a user. + type: array + items: + $ref: '#/components/schemas/Label' + releases: + description: A list of releases added and/or edited by a user. + type: array + items: + $ref: '#/components/schemas/Release' UserProfile: description: A type that represents a user profile. allOf: -- 2.52.0 From 0d104ef173504d3a996f5fe486657b44b82df86b Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Wed, 15 Oct 2025 23:55:43 +0200 Subject: [PATCH 5/6] Defined the GET /users/{username}/contributions endpoint for the Open API specification document in the library target. --- Sources/DiscogsService/openapi.yaml | 57 ++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml index ccb2b60e1..ba3af89d7 100644 --- a/Sources/DiscogsService/openapi.yaml +++ b/Sources/DiscogsService/openapi.yaml @@ -968,6 +968,47 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' + /users/{username}/contributions: + get: + tags: + - User Identity + summary: Get contributions of a user. + description: | + Retrieves all the contributions or additions to releases, labels, and artist done by username. + + This endpoints accepts pagination headers. + operationId: getUserContributions + parameters: + - $ref: '#/components/parameters/Username' + - $ref: '#/components/parameters/SortField' + - $ref: '#/components/parameters/SortOrder' + responses: + '200': + description: Successfully retrieved items contributed by a user. + headers: + X-Discogs-RateLimit: + $ref: '#/components/headers/RateLimit' + X-Discogs-RateLimit-Used: + $ref: '#/components/headers/RateLimitUsed' + X-Discogs-RateLimit-Remaining: + $ref: '#/components/headers/RateLimitRemaining' + content: + application/json: + schema: + type: object + properties: + pagination: + $ref: '#/components/schemas/Pagination' + submissions: + description: A type that represents all items submitted by a user. + $ref: '#/components/schemas/UserItems' + required: + - pagination + - contributions + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalError' /users/{username}/submissions: get: tags: @@ -1217,11 +1258,25 @@ components: in: query schema: type: string + SortField: + description: A filter by field. + name: sort + in: query + schema: + type: string + enum: + - label + - artist + - title + - catno + - format + - rating + - year + - added SortOrder: description: The order to sort the results. name: sort_order in: query - required: false schema: type: string enum: -- 2.52.0 From 2519fa7857307ac4bd18982570f7b1e1a2630151 Mon Sep 17 00:00:00 2001 From: Javier Cicchelli Date: Wed, 15 Oct 2025 23:56:28 +0200 Subject: [PATCH 6/6] Added some missing required properties in the 200 responses of some endpoints for the Open API specification document in the library target. --- Sources/DiscogsService/openapi.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml index ba3af89d7..82cd8b42a 100644 --- a/Sources/DiscogsService/openapi.yaml +++ b/Sources/DiscogsService/openapi.yaml @@ -508,6 +508,9 @@ paths: - $ref: '#/components/schemas/MasterResult' - $ref: '#/components/schemas/ArtistResult' - $ref: '#/components/schemas/LabelResult' + required: + - pagination + - results '401': $ref: '#/components/responses/Unauthorized' '500': @@ -576,6 +579,9 @@ paths: type: array items: $ref: '#/components/schemas/ArtistRelease' + required: + - pagination + - releases '404': $ref: '#/components/responses/NotFound' /labels/{label_id}: @@ -640,6 +646,9 @@ paths: type: array items: $ref: '#/components/schemas/LabelRelease' + required: + - pagination + - releases '404': $ref: '#/components/responses/NotFound' /masters/{master_id}: @@ -713,6 +722,9 @@ paths: type: array items: $ref: '#/components/schemas/ReleaseVersion' + required: + - pagination + - versions '404': $ref: '#/components/responses/NotFound' /releases/{release_id}: -- 2.52.0