diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml index 0284414c5..468fce083 100644 --- a/Sources/DiscogsService/openapi.yaml +++ b/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: ; rel="next", ; 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