Cleanup openapi spec to match more strict measures

Measures are applied through Insomnia on import, and while we could add
exceptions, being more specific with the fields isn't a bad thing to do
in this case.

spec/openapi.yaml

@@ -2,6 +2,10 @@ openapi: "3.1.0"
 info:
   version: 1.1.0
   title: Eclipse Foundation Git ECA API
+  description: Collection of API endpoints used in the validation and management of external Git services, such as Gitlab and Github.
+  contact:
+    name: IT support
+    url: https://gitlab.eclipse.org/eclipsefdn/it/api/git-eca-rest-api/-/issues
   license:
     name: Eclipse Public License - 2.0
     url: https://www.eclipse.org/legal/epl-2.0/
@@ -11,10 +15,15 @@ servers:
 tags:
   - name: ECA Validation
     description: Definitions in relation to the validation of Git commits through ECA signage
+  - name: Reports
+    description: Reports on metadata associated with Git systems managed by the Eclipse Foundation
+  - name: Integration Webhooks
+    description: Endpoints related to binding to external Git services through a webhook
 
 paths:
   /eca:
     post:
+      operationId: validate
       tags:
         - ECA Validation
       summary: ECA validation
@@ -25,29 +34,36 @@ paths:
             schema:
               $ref: "#/components/schemas/ValidationRequest"
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ValidationResponse"
-        500:
+        "500":
           description: Error while retrieving data
-
   /eca/status/{fingerprint}:
+    parameters:
+       - name: fingerprint
+         in: path
+         description: Unique ID for the request group
+         required: true
+         schema:
+            type: string
     get:
+      operationId: getCommitValidation
       tags:
-        - ECA Validation Status
+        - ECA Validation
       summary: Historic ECA validation status
       description: Returns a set of validation messages for the given unique fingerprint
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/CommitValidationStatuses"
-        500:
+        "500":
           description: Error while retrieving data
 
   /eca/status/{fingerprint}/ui:
@@ -59,34 +75,41 @@ paths:
          schema:
             type: string
     get:
+      operationId: getCommitValidationUI
+      tags:
+        - ECA Validation
       summary: Historic ECA validation status in a HTML format
       description: Returns an HTMl page containing validation messages
       responses:
-        200:
+        "200":
           description: Success. An HTML page containing status info
-        404:
+        "404":
           description: Not Found
-        500:
+        "500":
           description: Error while retrieving data
 
   /eca/lookup:
     get:
+      operationId: getUserStatus
+      tags:
+        - ECA Validation
       summary: User status lookup
       description: Returns wether or not the user has a signed ECA
       responses:
-        200:
+        "200":
           description: Success
-        403:
+        "403":
           description: User exists with no ECA
-        404:
+        "404":
           description: User not found
-        500:
+        "500":
           description: Error while retrieving data
 
   /webhooks/github:
     post:
+      operationId: processGithubWebhook
       tags:
-        - Github validation processing
+        - Integration Webhooks
       summary: Github incoming hook event processing
       description: Process incoming pull request hook events from Github
       parameters:
@@ -111,9 +134,9 @@ paths:
             schema:
               $ref: "#/components/schemas/GithubWebhookEvent"
       responses:
-        200:
+        "200":
           description: Success
-        500:
+        "500":
           description: Error while processing data
   /webhooks/github/revalidate/{fingerprint}:
     parameters:
@@ -124,8 +147,9 @@ paths:
          schema:
             type: string
     post:
+      operationId: revalidateWebhookRequest
       tags:
-        - Github validation processing
+        - Integration Webhooks
       summary: Gitlab webhook revalidation request
       description: Process incoming system hooks from GitLab
       requestBody:
@@ -134,20 +158,21 @@ paths:
             schema:
               $ref: '#/components/schemas/RevalidationRequest'
       responses:
-        200:
+        "200":
           description: Success
-        400:
+        "400":
           description: Bad request
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        404:
+        "404":
           description: Not found
   /webhooks/gitlab/system:
     post:
+      operationId: processGitlabHook
       tags:
-        - Gitlab system event processing
+        - Integration Webhooks
       summary: Gitlab event processing
       description: Process incoming system hooks from GitLab
       parameters:
@@ -162,9 +187,9 @@ paths:
             schema:
               $ref: "#/components/schemas/SystemHook"
       responses:
-        200:
+        "200":
           description: Success
-        500:
+        "500":
           description: Error while processing data
 
   /reports/gitlab/private-projects:
@@ -194,26 +219,27 @@ paths:
         schema:
           type: string
     get:
+      operationId: getPrivateProjectEvents
       tags:
-        - Private project event report
+        - Reports
       summary: Gitlab private project event report
       description: Returns list of private project events using desired filters
       responses:
-        200:
+        "200":
           description: Success
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/PrivateProjectEvents"
-        400:
+        "400":
           description: Bad Request - invalid non-null prams
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
-        401:
+        "401":
           description: Unauthorized - invalid key
-        500:
+        "500":
           description: Error while processing request
 
 components: