[BACK-2780] Add new and legacy user profile endpoint documentation.

.gitignore

@@ -4,3 +4,4 @@ build
 .idea/
 /node_modules/
 /tools/
+.DS_Store

reference/auth.v1.yaml

@@ -31,6 +31,9 @@ tags:
     description: APIs intended for internal use by Tidepool.
   - name: Users
     description: List and manage users.
+  - name: Profiles
+    description: |-
+      Create and update user profiles.
 paths:
   /auth/login:
     post:
@@ -680,6 +683,175 @@ paths:
         - sessionToken: []
       tags:
         - Internal
+  '/v1/users/{userId}/profile':
+    parameters:
+      - $ref: ./common/parameters/tidepooluserid.yaml
+    get:
+      operationId: GetUserProfile
+      summary: Get a user's profile
+      description: Returns the user's profile specified by the `userId`.
+      responses:
+        '200':
+          $ref: '#/components/responses/UserProfile'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      tags:
+        - Profiles
+      security:
+        - sessionToken: []
+    post:
+      operationId: UpdateUserProfile
+      summary: Creates or updates a user's profile
+      description: Upserts or updates the user profile specified by the `userId`. Due to legacy reasons, this operates as POST request if the profile does not exist or a PUT request if it does.
+      requestBody:
+        $ref: '#/components/requestBodies/UpdateUserProfile'
+      responses:
+        '200':
+          $ref: '#/components/responses/UserProfile'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      tags:
+        - Profiles
+      security:
+        - sessionToken: []
+    put:
+      operationId: UpdateUserProfile
+      summary: Creates or updates a user's profile
+      description: Upserts or updates the user profile specified by the `userId`. Due to legacy reasons, this operates as POST request if the profile does not exist or a PUT request if it does.
+      requestBody:
+        $ref: '#/components/requestBodies/UpdateUserProfile'
+      responses:
+        '200':
+          $ref: '#/components/responses/UserProfile'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      tags:
+        - Profiles
+      security:
+        - sessionToken: []
+    delete:
+      operationId: DeleteUserProfile
+      summary: Delete a user's profile
+      description: Delete the user profile specified by `userId`.
+      responses:
+        '200':
+          description: Success
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      tags:
+        - Profiles
+      security:
+        - sessionToken: []
+  '/v1/users/legacy/{userId}/profile':
+    parameters:
+      - $ref: ./common/parameters/tidepooluserid.yaml
+    get:
+      operationId: GetLegacyUserProfile
+      summary: Get a user's profile in the legacy format.
+      description: Returns the user's profile in the legacy seagull format specified by the `userId`.
+      responses:
+        '200':
+          $ref: '#/components/responses/UserProfile'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      tags:
+        - Profiles
+      security:
+        - sessionToken: []
+    post:
+      operationId: UpdateLegacyUserProfile
+      summary: Create or updates a user's profile in the legacy format.
+      description: Upserts or updates the user profile specified by the `userId`. Due to legacy reasons, this operates as POST request if the profile does not exist or a PUT request if it does.
+      requestBody:
+        $ref: '#/components/requestBodies/UpdateLegacyUserProfile'
+      responses:
+        '200':
+          $ref: '#/components/responses/LegacyUserProfile'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      tags:
+        - Profiles
+      security:
+        - sessionToken: []
+    put:
+      operationId: UpdateLegacyUserProfile
+      summary: Create or updates a user's profile in the legacy format.
+      description: Upserts or updates the user profile specified by the `userId`. Due to legacy reasons, this operates as POST request if the profile does not exist or a PUT request if it does.
+      requestBody:
+        $ref: '#/components/requestBodies/UpdateLegacyUserProfile'
+      responses:
+        '200':
+          $ref: '#/components/responses/LegacyUserProfile'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      tags:
+        - Profiles
+      security:
+        - sessionToken: []
+    delete:
+      operationId: DeleteUserProfile
+      summary: Delete a user's profile
+      description: Delete the user profile specified by `userId`.
+      responses:
+        '200':
+          description: Success
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      tags:
+        - Profiles
+      security:
+        - sessionToken: []
+  '/v1/users/{userId}/users':
+    parameters:
+      - $ref: './common/parameters/tidepooluserid.yaml'
+    get:
+      operationId: ListUsers
+      summary: List Users
+      description: >-
+        List all users who have trustee or trustor access to the user account identified by `userId`.
+      responses:
+        '200':
+          $ref: '#/components/responses/TrustUsers'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      tags:
+        - Profiles
+      security:
+        - sessionToken: []
 components:
   securitySchemes:
     basicAuth:
@@ -740,6 +912,18 @@ components:
           schema:
             oneOf:
               - $ref: ./auth/models/devicetoken-apple.v1.yaml
+    UpdateUserProfile:
+      description: Updated user profile
+      content:
+        application/json:
+          schema:
+            $ref: ./auth/models/profile/profile.v1.yaml
+    UpdateLegacyUserProfile:
+      description: Updated legacy user profile
+      content:
+        application/json:
+          schema:
+            $ref: ./auth/models/profile/legacyprofile.v1.yaml
   responses:
     User:
       description: Tidepool User Account
@@ -811,6 +995,24 @@ components:
         application/json:
           schema:
             $ref: ./auth/models/providers/sessions.v1.yaml
+    UserProfile:
+      description: User profile
+      content:
+        application/json:
+          schema:
+            $ref: ./auth/models/profile/profile.v1.yaml
+    LegacyUserProfile:
+      description: Legacy user profile compatible with seagull
+      content:
+        application/json:
+          schema:
+            $ref: ./auth/models/profile/legacyprofile.v1.yaml
+    TrustUsers:
+      description: 'Success'
+      content:
+        application/json:
+          schema:
+            $ref: './metadata/models/trustusers.v1.yaml'
     Unauthorized:
       description: Unauthorized
       content:

reference/auth/models/profile/legacyprofile.v1.yaml

@@ -0,0 +1,44 @@
+title: Legacy User Profile
+description: >-
+  Legacy user profile compatible with seagull returned by platform.
+type: object
+properties:
+  fullName:
+    $ref: '../../../metadata/models/fullname.v1.yaml'
+  email:
+    $ref: '../../../common/models/emailaddress.v1.yaml'
+  emails:
+    $ref: '../emailaddresses.v1.yaml'
+  patient:
+    type: object
+    description: 'Embedded legacy patient profile'
+    properties:
+      birthday:
+        $ref: '../../../common/models/birthday.v1.yaml'
+      diagnosisType:
+        $ref: '../../../metadata/models/diagnosistype.v1.yaml'
+      diagnosisDate:
+        $ref: '../../../common/models/diagnosisdate.v1.yaml'
+      biologicalSex:
+        $ref: '../../../metadata/models/biologicalsex.v1.yaml'
+      targetDevices:
+        $ref: '../../../metadata/models/targetdevices.v1.yaml'
+      targetTimezone:
+        $ref: '../../../metadata/models/targettimezone.v1.yaml'
+      about:
+        $ref: '../../../metadata/models/about.v1.yaml'
+      isOtherPerson:
+        type: boolean
+  clinic:
+    type: object
+    properties:
+      name:
+        type: string
+        description: 'Name of the clinic'
+      role:
+        $ref: '../role.v1.yaml'
+      telephone:
+        type: string
+      npi:
+        type: string
+

reference/auth/models/profile/profile.v1.yaml

@@ -0,0 +1,41 @@
+title: User Profile
+description: >-
+  User profile returned by platform.
+type: object
+properties:
+  fullName:
+    $ref: '../../../metadata/models/fullname.v1.yaml'
+  birthday:
+    $ref: '../../../common/models/birthday.v1.yaml'
+  diagnosisType:
+    $ref: '../../../metadata/models/diagnosistype.v1.yaml'
+  diagnosisDate:
+    $ref: '../../../common/models/diagnosisdate.v1.yaml'
+  biologicalSex:
+    $ref: '../../../metadata/models/biologicalsex.v1.yaml'
+  targetDevices:
+    $ref: '../../../metadata/models/targetdevices.v1.yaml'
+  targetTimezone:
+    $ref: '../../../metadata/models/targettimezone.v1.yaml'
+  about:
+    $ref: '../../../metadata/models/about.v1.yaml'
+  mrn:
+    $ref: '../../../metadata/models/mrn.v1.yaml'
+  custodian:
+    type: object
+    properties:
+      fullName:
+        $ref: '../../../metadata/models/fullname.v1.yaml'
+  clinic:
+    type: object
+    properties:
+      name:
+        type: string
+        description: 'Name of the clinic'
+      role:
+        $ref: '../role.v1.yaml'
+      telephone:
+        type: string
+      npi:
+        type: string
+