[PLAT-931] Add External Identities endpoints to docs

swagger-spec/swagger.yaml

@@ -1253,6 +1253,12 @@ paths:
   /users/{user_id}/:
     $ref: 'users/detail.yaml'
 
+  /users/{user_id}/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,96 @@
+get:
+  summary: Retrieve user's external identities
+  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.
+
+    #### 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: definition.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: Delete user's external identities
+  description: >-
+    Deletes  a user's external identity.
+
+    The returns deleted information including the external identity's name, status and id.
+
+    #### 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: definition.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
+

swagger-spec/users/external_identities_list.yaml

@@ -0,0 +1,43 @@
+get:
+  summary: List all user's 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.
+
+    #### 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:
+        $ref: definition.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
+