User Identity endpoints (#11)

This PR contains the work done to implement the *User Identity* endpoints of the **Discogs API** online service:
* GET `/users/{username}`
* POST `/users/{username}`
* GET `/users/{username}/contributions`
* GET `/users/{username}/submissions`

Reviewed-on: #11
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

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: []
+        - UserToken: []
-        - KeySecret: []
+        - ConsumerKeySecret: []
         - OAuth: []
       responses:
         '200':
@@ -477,8 +477,8 @@ paths:
         - $ref: '#/components/parameters/Page'
         - $ref: '#/components/parameters/PerPage'
       security:
-        - Token: []
+        - UserToken: []
-        - KeySecret: []
+        - ConsumerKeySecret: []
         - OAuth: []
       responses:
         '200':
@@ -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}:
@@ -806,8 +818,8 @@ paths:
         - $ref: '#/components/parameters/Username'
         - $ref: '#/components/parameters/Rating'
       security:
-        - Token: []
+        - UserToken: []
-        - KeySecret: []
+        - ConsumerKeySecret: []
         - OAuth: []
       responses:
         '200':
@@ -842,8 +854,8 @@ paths:
         - $ref: '#/components/parameters/ReleaseId'
         - $ref: '#/components/parameters/Username'
       security:
-        - Token: []
+        - UserToken: []
-        - KeySecret: []
+        - ConsumerKeySecret: []
         - OAuth: []
       responses:
         '200':
@@ -896,6 +908,158 @@ paths:
                       - is_offensive
         '404':
           $ref: '#/components/responses/NotFound'
+  /users/{username}:
+    get:
+      tags:
+        - User Identity
+      summary: Get information about a user.
+      description: |
+        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.
+        
+        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'
+      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'
+    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'
+  /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:
+        - 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:
@@ -1002,6 +1166,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
@@ -1016,6 +1188,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
@@ -1037,6 +1216,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
@@ -1054,6 +1240,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
@@ -1077,11 +1270,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: 
@@ -1116,6 +1323,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:
@@ -1125,7 +1340,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:
@@ -1754,9 +1969,7 @@ components:
         - status
         - styles
         - title
-        - tracklist
         - uri
-        - videos
     ReleaseFormat:
       description: A type that represents a format of a release.
       type: object
@@ -2073,7 +2286,6 @@ components:
           type: string
           format: uri
       required:
-        - id
         - resource_url
         - username
     UserIdentity:
@@ -2085,6 +2297,183 @@ 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:
+        - $ref: '#/components/schemas/UserId'
+        - type: object
+          properties:
+            name:
+              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 biographical information of a user.
+              type: string
+            location:
+              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 a website 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
@@ -2113,7 +2502,7 @@ components:
         - title
         - uri
   securitySchemes:
-    KeySecret:
+    ConsumerKeySecret:
       description: |
         Discogs authentication using a key/secret pair. 
         
@@ -2133,7 +2522,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.