feat: Update openapi spec with better examples, tags, and formatting

Resolves #59 (closed)

spec/openapi.yaml

@@ -6,11 +6,21 @@ info:
   license:
     name: Eclipse Public License - 2.0
     url: https://www.eclipse.org/legal/epl-2.0/
+  contact:
+    url: https://gitlab.eclipse.org/eclipsefdn/it/api/eclipsefdn-profile-api/-/issues
 
 servers:
-  - url: https://api.eclipse.org/sandbox/
+  - url: https://api.eclipse.org/sandbox
     description: Production endpoints for Eclipse Foundation profile data
 
+tags:
+  - name: User Profile
+    description: Profile data for a user
+  - name: User Metadata
+    description: Additional user metadata
+  - name: User Delete Request
+    description: User delete request processing
+
 paths:
   /account/profile:
     get:
@@ -18,8 +28,10 @@ paths:
         - User Profile
       summary: Search for user or get current user
       description: Retrieve information about a user with given params, or the user making the request.
+      operationId: UserSearch
       security:
-        - OAuth2: [eclipsefdn_view_all_profiles]
+        - OAuth2:
+            - eclipsefdn_view_all_profiles
       parameters:
         - name: uid
           in: query
@@ -40,32 +52,34 @@ paths:
           schema:
             type: string
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/EfUsers"
-        403:
+        "403":
           description: Invalid authentication
-        404:
+        "404":
           description: User not found
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        500:
+        "500":
           description: Error while retrieving data.
 
   /account/profile/{name}:
     get:
       tags:
-        - User Profiles
-      summary: Retrieve user
+        - User Profile
+      summary: Retrieve user via Ef Username
       description: Retrieve profile information about a specified user.
-      operationId: RetrieveUser
+      operationId: RetrieveUserEf
       security:
-        - OAuth2: [eclipsefdn_view_all_profiles]
+        - BasicAuth: []
+        - OAuth2:
+            - eclipsefdn_view_all_profiles
       parameters:
         - name: name
           in: path
@@ -76,31 +90,33 @@ paths:
           schema:
             type: string
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/EfUser"
-        404:
+        "404":
           description: User not found
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        500:
+        "500":
           description: Error while retrieving data.
       deprecated: false
 
   /github/profile/{handle}:
     get:
       tags:
-        - User Profiles
-      summary: Retrieve user
+        - User Profile
+      summary: Retrieve user via Github handle
       description: Retrieve profile information about a specified user.
-      operationId: RetrieveUser
+      operationId: RetrieveUserGh
       security:
-        - OAuth2: [eclipsefdn_view_all_profiles]
+        - BasicAuth: []
+        - OAuth2:
+            - eclipsefdn_view_all_profiles
       parameters:
         - name: handle
           in: path
@@ -111,28 +127,31 @@ paths:
           schema:
             type: string
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/EfUser"
-        404:
+        "404":
           description: User not found
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        500:
+        "500":
           description: Error while retrieving data.
       deprecated: false
 
   /account/profile/{name}/eca:
     get:
       tags:
-        - Related User Metadata
-      summary: Retrieve user eca status
+        - User Metadata
+      summary: Retrieve user eca status via username
       description: Retrieve eca status about a specified user.
+      operationId: RetrieveEca
+      security:
+        - BasicAuth: []
       parameters:
         - name: name
           in: path
@@ -143,28 +162,28 @@ paths:
           schema:
             type: string
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Eca"
-        404:
-          description: User not found
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/Error"
-        500:
+              example:
+                signed: true
+                can_contribute_spec_project: true
+        "500":
           description: Error while retrieving data.
       deprecated: false
 
   /account/profile/{name}/mailing-list:
     get:
       tags:
-        - Related User Metadata
-      summary: Retrieve user mailing-list subscriptions
+        - User Metadata
+      summary: Retrieve user mailing-list subscriptions via username
       description: Retrieve mailing-list subscriptions for a specified user.
+      operationId: RetrieveMailingList
+      security:
+        - BasicAuth: []
       parameters:
         - name: name
           in: path
@@ -175,22 +194,25 @@ paths:
           schema:
             type: string
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Subscriptions"
-        500:
+        "500":
           description: Error while retrieving data.
       deprecated: false
 
   /account/profile/{name}/projects:
     get:
       tags:
-        - Related User Metadata
-      summary: Retrieve user projects
+        - User Metadata
+      summary: Retrieve user projects via username
       description: Retrieve projects for a specified user.
+      operationId: RetrieveProjects
+      security:
+        - BasicAuth: []
       parameters:
         - name: name
           in: path
@@ -201,22 +223,25 @@ paths:
           schema:
             type: string
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/PeopleProjectMap"
-        500:
+        "500":
           description: Error while retrieving data.
       deprecated: false
 
   /account/profile/{name}/gerrit:
     get:
       tags:
-        - Related User Metadata
-      summary: Retrieve user gerrit merge count
+        - User Metadata
+      summary: Retrieve user gerrit merge count via username
       description: Retrieve gerrit merge count data about a specified user.
+      operationId: RetrieveGerrit
+      security:
+        - BasicAuth: []
       parameters:
         - name: name
           in: path
@@ -227,19 +252,19 @@ paths:
           schema:
             type: string
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/GerritResponse"
-        404:
+        "404":
           description: User not found
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        500:
+        "500":
           description: Error while retrieving data.
       deprecated: false
 
@@ -247,10 +272,12 @@ paths:
     post:
       tags:
         - User Delete Request
-      summary: Initialize the user deletion process
+      summary: Initialize the user deletion process via username
       description: Initialize the user deletion process for a specified user.
+      operationId: CreateDeleteRequests
       security:
-        - OAuth2: [eclipsefdn_view_all_profiles]
+        - OAuth2:
+            - eclipsefdn_view_all_profiles
       parameters:
         - name: name
           in: path
@@ -259,27 +286,27 @@ paths:
           schema:
             type: string
       responses:
-        201:
+        "201":
           description: Created
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/UserDeleteRequests"
-        403:
+        "403":
           description: Invalid authentication
-        404:
+        "404":
           description: User not found
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        409:
+        "409":
           description: Conflict - Records already exist
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        500:
+        "500":
           description: Error while retrieving data.
       deprecated: false
 
@@ -287,10 +314,12 @@ paths:
     get:
       tags:
         - User Delete Request
-      summary: Retrieve list of user delete requests
+      summary: Retrieve list of user delete requests via params
       description: Retrieve a list of user delete requests filtered by desired parameters
+      operationId: RetrieveDeleteRequests
       security:
-        - OAuth2: [eclipsefdn_view_all_profiles]
+        - OAuth2:
+            - eclipsefdn_view_all_profiles
       parameters:
         - name: uid
           in: query
@@ -335,15 +364,13 @@ paths:
           schema:
             type: integer
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/UserDeleteRequests"
-        403:
-          description: Invalid authentication
-        500:
+        "500":
           description: Error while retrieving data.
 
   /account/user_delete_request/{request_id}:
@@ -352,8 +379,10 @@ paths:
         - User Delete Request
       summary: Retrieve a user delete request by id
       description: Retrieve a user delete request by id
+      operationId: RetrieveDeleteRequest
       security:
-        - OAuth2: [eclipsefdn_view_all_profiles]
+        - OAuth2:
+            - eclipsefdn_view_all_profiles
       parameters:
         - name: request_id
           in: path
@@ -362,29 +391,31 @@ paths:
           schema:
             type: integer
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/UserDeleteRequest"
-        403:
+        "403":
           description: Invalid authentication
-        404:
+        "404":
           description: Delete Request not found.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        500:
+        "500":
           description: Error while retrieving data.
     put:
       tags:
         - User Delete Request
       summary: Update a user delete request by id
       description: Update a user delete request by id
+      operationId: UpdateDeleteRequest
       security:
-        - OAuth2: [eclipsefdn_view_all_profiles]
+        - OAuth2:
+            - eclipsefdn_view_all_profiles
       parameters:
         - name: request_id
           in: path
@@ -400,31 +431,33 @@ paths:
             schema:
               $ref: "#/components/schemas/RequestStatusUpdate"
       responses:
-        204:
+        "204":
           description: Success - No content
-        400:
+        "400":
           description: Bad Request - invalid request body.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        403:
+        "403":
           description: Invalid authentication
-        404:
+        "404":
           description: Delete Request not found.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        500:
+        "500":
           description: Error while modifying data.
     delete:
       tags:
         - User Delete Request
       summary: Delete a user delete request by id
       description: Delete a user delete request by id
+      operationId: DeleteDeleteRequest
       security:
-        - OAuth2: [eclipsefdn_view_all_profiles]
+        - OAuth2:
+            - eclipsefdn_view_all_profiles
       parameters:
         - name: request_id
           in: path
@@ -433,57 +466,91 @@ paths:
           schema:
             type: integer
       responses:
-        204:
+        "204":
           description: Success - No content
-        403:
+        "403":
           description: Invalid authentication
-        404:
+        "404":
           description: Delete Request not found.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        500:
+        "500":
           description: Error while modifying data.
 
 components:
-  headers:
-    X-RateLimit-Limit:
-      schema:
-        type: string
-      example: 1000
-    X-RateLimit-Remaining:
-      schema:
-        type: string
-      example: 964
-    X-RateLimit-Reset:
-      schema:
-        type: string
-      example: 3553
+  securitySchemes:
+    BasicAuth:
+      type: http
+      scheme: basic
+    OAuth2:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://accounts.eclipse.org/oauth2/token
+          scopes:
+            eclipsefdn_view_all_profiles: Access private profile information
 
   schemas:
     EfUsers:
       type: array
       items:
         $ref: "#/components/schemas/EfUser"
+      example:
+        - uid: 606609
+          name: zacharysabourin
+          mail: zachary.sabourin@eclipse-foundation.org
+          picture: https://secure.gravatar.com/avatar/fbbbb03860062596a5cf11105dcc7d47.jpg?d=mm&s=185&r=G
+          eca:
+            signed: true
+            can_contribute_spec_project: true
+          is_committer: true
+          first_name: Zachary
+          last_name: Sabourin
+          github_handle: zacharysabourin
+          twitter_handle: sometwitteruser
+          publisher_agreements:
+            "open-vsx":
+              version: "1"
+          org: Eclipse Foundation
+          org_id: null
+          job_title: Web Developer
+          website: https://google.com
+          country:
+            code: CA
+            name: Canada
+          bio: This is my bio. Hello!
+          interests:
+            - MTG
+            - Warhammer
+            - Bass guitar
+          working_groups_interests:
+            - adoptium
+            - oniro
+          eca_url: https://api.eclipse.org/sandbox/account/profile/zacharysabourin/eca
+          projects_url: https://api.eclipse.org/sandbox/account/profile/zacharysabourin/projects
+          gerrit_url: https://api.eclipse.org/sandbox/account/profile/zacharysabourin/gerrit
+          mailinglist_url: https://api.eclipse.org/sandbox/account/profile/zacharysabourin/mailing-list
+          mpc_favorites_url: https://api.eclipse.org/marketplace/favorites?name=zacharysabourin
 
     EfUser:
       type: object
       properties:
         uid:
           type: integer
-          description: The unique user id.
+          description: "The unique user id."
         name:
           type: string
-          description: The user's ef username name.
+          description: "The user's ef username name."
         picture:
           type: string
-          description: URL of the user's picture.
+          description: "URL of the user's picture."
         mail:
           oneOf:
             - type: string
             - type: "null"
-          description: The user's email.
+          description: "The user's email."
         eca:
           oneOf:
             - $ref: "#/components/schemas/Eca"
@@ -492,30 +559,28 @@ components:
           oneOf:
             - type: boolean
             - type: "null"
-          description: User's committer status.
-        friends:
-          oneOf:
-            - $ref: "#/components/schemas/Friends"
-            - type: "null"
+          description: "User's committer status."
         first_name:
           type: string
-          description: The user's first name.
+          description: "The user's first name."
         last_name:
           type: string
-          description: The user's last name.
+          description: "The user's last name."
         publisher_agreements:
           type: object
+          propertyNames:
+            description: The publisher agreement name.
           additionalProperties:
             $ref: "#/components/schemas/PublisherAgreement"
         github_handle:
           type: string
-          description: The user's Github handle.
+          description: "The user's Github handle."
         twitter_handle:
           type: string
-          description: The user's Twitter handle.
+          description: "The user's Twitter handle."
         org:
           type: string
-          description: The user's organization.
+          description: "The user's organization."
         org_id:
           oneOf:
             - type: string
@@ -523,52 +588,88 @@ components:
           description: The user's organization id.
         job_title:
           type: string
-          description: The user's job title at the organization.
+          description: "The user's job title at the organization."
         website:
           type: string
-          description: The user's website.
+          description: "The user's website."
         country:
           $ref: "#/components/schemas/Country"
         bio:
           oneOf:
             - type: string
             - type: "null"
-          description: The user's account bio
+          description: "The user's account bio"
         interests:
           type: array
           items:
             type: string
-          description: A list of the user's interests.
+          description: "A list of the user's interests."
         working_groups_interests:
           type: array
           items:
             type: string
-          description: A list of the user's working group interests.
+          description: "A list of the user's working group interests."
         forums_url:
           oneOf:
             - type: string
             - type: "null"
-          description: The user's forum URL.
+          description: "The user's forum URL."
         gerrit_url:
           oneOf:
             - type: string
             - type: "null"
-          description: The user's Gerrit URL.
+          description: "The user's Gerrit URL."
         projects_url:
           oneOf:
             - type: string
             - type: "null"
-          description: The user's projects URL.
+          description: "The user's projects URL."
         mailinglist_url:
           oneOf:
             - type: string
             - type: "null"
-          description: The user's mailing list URL.
+          description: "The user's mailing list URL."
         mpc_favorites_url:
           oneOf:
             - type: string
             - type: "null"
-          description: The user's Marketplace favorites URL.
+          description: "The user's Marketplace favorites URL."
+      example:
+        uid: 606609
+        name: zacharysabourin
+        mail: zachary.sabourin@eclipse-foundation.org
+        picture: https://secure.gravatar.com/avatar/fbbbb03860062596a5cf11105dcc7d47.jpg?d=mm&s=185&r=G
+        eca:
+          signed: true
+          can_contribute_spec_project: true
+        is_committer: true
+        first_name: Zachary
+        last_name: Sabourin
+        github_handle: zacharysabourin
+        twitter_handle: sometwitteruser
+        publisher_agreements:
+          "open-vsx":
+            version: "1"
+        org: Eclipse Foundation
+        org_id: null
+        job_title: Web Developer
+        website: https://google.com
+        country:
+          code: CA
+          name: Canada
+        bio: This is my bio. Hello!
+        interests:
+          - MTG
+          - Warhammer
+          - Bass guitar
+        working_groups_interests:
+          - adoptium
+          - oniro
+        eca_url: https://api.eclipse.org/sandbox/account/profile/zacharysabourin/eca
+        projects_url: https://api.eclipse.org/sandbox/account/profile/zacharysabourin/projects
+        gerrit_url: https://api.eclipse.org/sandbox/account/profile/zacharysabourin/gerrit
+        mailinglist_url: https://api.eclipse.org/sandbox/account/profile/zacharysabourin/mailing-list
+        mpc_favorites_url: https://api.eclipse.org/marketplace/favorites?name=zacharysabourin
 
     Eca:
       type: object
@@ -579,13 +680,9 @@ components:
         can_contribute_spec_project:
           type: boolean
           description: Flag determining whether users can contribute to a spec project.
-
-    Friends:
-      type: object
-      properties:
-        friend_id:
-          type: integer
-          description: The friend's userid.
+      example:
+        signed: true
+        can_contribute_spec_project: true
 
     Country:
       type: object
@@ -599,7 +696,9 @@ components:
           oneOf:
             - type: string
             - type: "null"
-          description: The country name.
+      example:
+        code: CA
+        name: Canada
 
     PublisherAgreement:
       type: object
@@ -607,6 +706,8 @@ components:
         version:
           type: string
           description: the agreement document version.
+      example:
+        version: "1"
 
     Error:
       type: object
@@ -622,6 +723,10 @@ components:
             - type: string
             - type: "null"
           description: The URL
+      example:
+        status_code: 404
+        message: "User zach not found"
+        url: ""
 
     Subscriptions:
       type: object
@@ -630,6 +735,12 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/MailingList"
+      example:
+        mailing_list_subscriptions:
+          - list_name: cross-project-issues-dev
+            list_description: Cross project issues
+          - list_name: epp
+            list_description: Eclipse Packaging Project
 
     MailingList:
       type: object
@@ -640,6 +751,9 @@ components:
         list_description:
           type: string
           description: The mailing list description.
+      example:
+        list_name: cross-project-issues-dev
+        list_description: Cross project issues
 
     PeopleProjectMap:
       type: object
@@ -647,11 +761,42 @@ components:
         description: The project ID
       additionalProperties:
         $ref: "#/components/schemas/PeopleProjects"
+      example:
+        technology.usssdk:
+          - active_date: "2022-09-21T00:00:00Z"
+            inactive_date: ""
+            edit_bugs: "0"
+            sort_order: ""
+            project_name: "Eclise USS SDK"
+            url: "https://projects.eclipse.org/projects/technology.usssdk"
+            specification_project: false
+            relation:
+              relation: CM
+              description: commiter
+              is_active: "1"
+              type:
+                type: PR
+                description: Person - Project
 
     PeopleProjects:
       type: array
       items:
         $ref: "#/components/schemas/PeopleProject"
+      example:
+        - active_date: "2022-09-21T00:00:00Z"
+          inactive_date: ""
+          edit_bugs: "0"
+          sort_order: ""
+          project_name: "Eclise USS SDK"
+          url: "https://projects.eclipse.org/projects/technology.usssdk"
+          specification_project: false
+          relation:
+            relation: CM
+            description: commiter
+            is_active: "1"
+            type:
+              type: PR
+              description: Person - Project
 
     PeopleProject:
       type: object
@@ -681,6 +826,21 @@ components:
           description: The active date for tis record
         relation:
           $ref: "#/components/schemas/Relation"
+      example:
+        active_date: "2022-09-21T00:00:00Z"
+        inactive_date: ""
+        edit_bugs: "0"
+        sort_order: ""
+        project_name: "Eclise USS SDK"
+        url: "https://projects.eclipse.org/projects/technology.usssdk"
+        specification_project: false
+        relation:
+          relation: CM
+          description: commiter
+          is_active: "1"
+          type:
+            type: PR
+            description: Person - Project
 
     Relation:
       type: object
@@ -696,6 +856,13 @@ components:
           description: The active flag for the relation. 1 for true, 0 for false.
         type:
           $ref: "#/components/schemas/RelationType"
+      example:
+        relation: CM
+        description: commiter
+        is_active: "1"
+        type:
+          type: PR
+          description: Person - Project
 
     RelationType:
       type: object
@@ -706,6 +873,9 @@ components:
         description:
           type: string
           description: The type description.
+      example:
+        type: PR
+        description: Person - Project
 
     GerritResponse:
       type: object
@@ -722,6 +892,11 @@ components:
         account_url:
           type: string
           description: The ef profile url.
+      example:
+        merged_changes_count: "99"
+        gerrit_owner_url: https://git.eclipse.org/r/changes/?q=owner:zachary.sabourin@eclipse-foundation.org
+        gerrit_reviewer_url: https://git.eclipse.org/r/changes/?q=owner:zachary.sabourin@eclipse-foundation.org
+        account_url: https://api.eclipse.org/account/profile/zacharysabourin
 
     UserDeleteRequests:
       type: array
@@ -739,7 +914,7 @@ components:
           description: The user uid
         name:
           type: string
-          description: The user's ef username
+          description: "The user's ef username"
         mail:
           type: string
           description: The user email