[PLAT-931] Add External Identities endpoints to docs

swagger-spec/external_identities/external_identities_detail.yaml

@@ -0,0 +1,31 @@
+type: object
+title: External Identity Detail
+properties:
+  id:
+    type: string
+    readOnly: true
+    description: 'The identifier of the external identity provider e.g. ORCID.'
+  type:
+    type: string
+    readOnly: true
+    description: 'The type identifier of the external identity entity (`external-identities`).'
+  attributes:
+    type: object
+    title: Attributes
+    readOnly: true
+    description: 'The properties of the  external identity entity.'
+    properties:
+      status:
+        type: string
+        readOnly: true
+        description: 'The status of the external identity e.g LINK or VERIFIED.'
+      external_id:
+        type: string
+        readOnly: true
+        description: 'The identifier for the user associated with that external identity.'
+  links:
+    type: object
+    title: Links
+    readOnly: true
+    description: 'URLs to alternative representations of the citation style entity.'
+

swagger-spec/swagger.yaml

@@ -1253,6 +1253,12 @@ paths:
   /users/{user_id}/:
     $ref: 'users/detail.yaml'
 
+  /users/{user_id}/settings/identities/:
+    $ref: 'users/external_identities_list.yaml'
+
+  /users/{user_id}/identities/{identities_id}/:
+    $ref: 'users/external_identities_detail.yaml'
+
   /users/{user_id}/institutions/:
     $ref: 'users/institutions_list.yaml'
 

swagger-spec/users/detail.yaml

@@ -1,7 +1,7 @@
 get:
   summary: Retrieve a user
   description: >-
-    Retrieves the details of a given users.
+    Retrieves the details for a given user.
 
 
     The returned information includes the user's bibliographic information and the date the user was registered.

swagger-spec/users/external_identities_detail.yaml

@@ -0,0 +1,90 @@
+get:
+  summary: Retrieve a external identity
+  description: >-
+    Retrieves a JSON object of a user's external identity, currently this only includes their ORCID account.
+
+    The returned information includes the external identity's name, status and id.
+
+    #### Permissions
+
+    External identities can only be viewed or deleted by the user they belong to.
+
+    #### Returns
+
+    Returns a JSON object with a `data` key containing the representation of the requested
+    external identities, if the request is successful.
+
+    If the request is unsuccessful, an `errors` key containing
+    information about the failure will be returned. Refer to the [list of error codes](#tag/Errors-and-Error-Codes)
+    to understand why this request may have failed.
+
+
+  parameters:
+  - in: path
+    type: string
+    name: user_id
+    required: true
+    description: 'The unique identifier of the user.'
+  - in: path
+    type: string
+    name: identities_id
+    required: true
+    description: "The unique identifier of a user's external identity."
+  tags:
+    - Users
+  operationId: external_identities_detail
+  responses:
+    '200':
+      description: 'OK'
+      schema:
+        $ref: '../external_identities/external_identities_detail.yaml'
+      examples:
+        application/json:
+          data:
+            links:
+              self: https://api.osf.io/v2/users/q7fts/settings/identities/ORCID/
+            attributes:
+              status: VERFIED
+              external_id: '0000-0001-9143-4652'
+              id: ORCID
+            type: users
+            id: q7fts
+
+delete:
+  summary: Remove a user's external identities
+  description: >-
+    Deletes  a user's external identity.
+
+    The returns deleted information including the external identity's name, status and id.
+
+    #### Permissions
+
+    External identities can only be viewed or deleted by the user they belong to.
+
+    #### Returns
+
+    If the request is successful, no content is returned.
+
+
+    If the request is unsuccessful, a JSON object with an errors key containing information about the failure will
+    be returned. Refer to the [list of error codes](#tag/Errors-and-Error-Codes) to understand why this request
+    may have failed.
+
+
+  parameters:
+  - in: path
+    type: string
+    name: user_id
+    required: true
+    description: 'The unique identifier of the user.'
+  - in: path
+    type: string
+    name: identities_id
+    required: true
+    description: "The unique identifier of a user's external identity."
+  tags:
+    - Users
+  operationId: external_identities_detail
+  responses:
+    '204':
+      description: 'NO CONTENT'

swagger-spec/users/external_identities_list.yaml

@@ -0,0 +1,49 @@
+get:
+  summary: List all external identities
+  description: >-
+    Retrieves a list of a user's external identities, currently this only includes their ORCID accounts.
+
+    The returned information includes the external identity's name, status and id.
+
+    #### Permissions
+
+    External identities can only be viewed or deleted by the user they belong to.
+
+    #### Returns
+
+    Returns a JSON object with a `data` key containing the representation of the requested
+    external identities, if the request is successful.
+
+    If the request is unsuccessful, an `errors` key containing
+    information about the failure will be returned. Refer to the [list of error codes](#tag/Errors-and-Error-Codes)
+    to understand why this request may have failed.
+
+
+  parameters:
+  - in: path
+    type: string
+    name: user_id
+    required: true
+    description: 'The unique identifier of the user.'
+  tags:
+    - Users
+  operationId: external_identities_list
+  responses:
+    '200':
+      description: 'OK'
+      schema:
+        type: array
+        items:
+          $ref: '../external_identities/external_identities_detail.yaml'
+      examples:
+        application/json:
+          data:
+            - links:
+                self: https://api.osf.io/v2/users/q7fts/settings/identities/ORCID/
+              attributes:
+                status: VERFIED
+                external_id: '0000-0001-9143-4652'
+                id: ORCID
+              type: users
+              id: q7fts
+