Sources/DiscogsService/openapi.yaml

@@ -227,7 +227,9 @@ servers:
     description: Live Server
 tags:
   - name: Service
-    description: Access data related to the service.
+    description: Access data on the service.
+  - name: Authentication
+    description: Access data on authenticating to the service.
   - name: Database
     description: Access data on artists, labels, and releases.    
   - name: Marketplace
@@ -266,13 +268,48 @@ paths:
                 $ref: '#/components/schemas/Service'
         '500':
           $ref: '#/components/responses/Unavailable'
+  /oauth/request_token:
+    get:
+      tags:
+        - Authentication
+      summary: Get details about a OAuth request token.
+      description: |
+        Retrieve a request token to initialize an *OAuth* authentication process.
+
+        This endpoint represents the [2nd step of the OAuth flow process](https://www.discogs.com/developers#header-2.-send-a-get-request-to-the-discogs-request-token-url), thus it requires to configure an *Authorization* header to have a value like this:
+        
+        ```
+        OAuth oauth_consumer_key="your_consumer_key", oauth_nonce="random_string_or_timestamp", oauth_signature="your_consumer_secret&", oauth_signature_method="PLAINTEXT", oauth_timestamp="current_timestamp", oauth_callback="your_callback"
+        ```
+
+        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: getRequestToken
+      parameters:
+        - $ref: '#/components/parameters/ContentType'
+        - $ref: '#/components/parameters/Authorization'
+        - $ref: '#/components/parameters/UserAgent'
+      responses:
+        '200':
+          description: |
+            Successfully retrieved request token details.
+
+            With this request token, then it is possible to continue with the [next step in the OAuth flow](https://www.discogs.com/developers#header-3.-redirect-your-user-to-the-discogs-authorize-page) process.
+          headers:
+            oauth_token:
+              $ref: '#/components/headers/OAuthToken'
+            oauth_token_secret: 
+              $ref: '#/components/headers/OAuthSecret'
+            oauth_callback-confirmed:
+              $ref: '#/components/headers/OAuthCallback'
+        '500':
+          $ref: '#/components/responses/InternalError'
   /artists/{artist_id}:
     get:
-      summary: Get information about an artist.
-      operationId: getArtist
-      description: Retrieves any available information for a specific artist.
       tags:
         - Database
+      summary: Get information about an artist.
+      description: Retrieves any available information for a specific artist.
+      operationId: getArtist
       parameters:
         - $ref: '#/components/parameters/ArtistId'
       responses:
@@ -808,6 +845,19 @@ components:
         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"
       required: true
+    OAuthCallback:
+      description: An OAuth callback confirmed.
+      schema:
+        type: boolean
+        default: true
+    OAuthSecret:
+      description: An OAuth request token secret.
+      schema:
+        type: string
+    OAuthToken:
+      description: An OAuth request token.
+      schema:
+        type: string
     RateLimit:
       description: A total number of requests that can be made in a minute window.
       schema:
@@ -852,6 +902,23 @@ components:
           - year
           - title
           - format
+    Authorization:
+      name: Authorization
+      description: A string to authenticate a user with a service by carrying credentials.
+      in: header
+      required: true
+      schema:
+        type: string
+    ContentType:
+      name: Content-Type
+      description: A content type for a response.
+      in: header
+      required: true
+      schema:
+        type: string
+        enum:
+          - application/json
+          - application/x-www-form-urlencoded
     Country:
       description: A filter by country.
       name: country
@@ -958,6 +1025,13 @@ components:
         enum: 
           - asc
           - desc
+    UserAgent:
+      name: User-Agent
+      description: A name of a software agent responsible for interacting with the service.
+      in: header
+      required: true
+      schema:
+        type: string
     Username:
       description: A username of a user.
       name: username