Upd: Endpoint descriptions and summary for config and audit

Signed-off-by: Lal Chandran <[email protected]>

openapi/v2023.11.1/index.yaml

@@ -193,7 +193,6 @@ paths:
   /onboard/password/forgot:
     put:
       $ref: "./paths/onboardForgotPassword.yaml"
-
   /onboard/admin/login:
     post:
       $ref: ./paths/loginOrganisationAdmin.yaml
@@ -339,21 +338,26 @@ servers:
     url: https://demo-consent-bb-api.igrant.io/v2
 tags:
   - description:
-      Operations for external auditing systems to query detailed data from
-      the system and subscribe to notifications.
+      This consists of endpoints for an external auditing systems or for organisational to query 
+      consent record from consent building block.
     name: audit
     x-tag-expanded: false
-  - description: Secured operations available to organization API integration
+  - description: 
+      This consists of ndpoints available to organisation admins to manage data agreements, 
+      data agreement records, consents and consent records. It also provides mechanisms 
+      onboard the organisation to consent building block. 
     name: config
     x-tag-expanded: false
   - description:
-      Secured operations for individuals, data consumers and applications
-      to record and verify consent
+      This consists of endpoints towards individuals, data consumers and applications
+      to view, sign/record their agreement to the processing of personal data. In cases
+      where the data agreement is of legal basis consent and for legitimate interest, 
+      the individual can opt-in and opt-out at any stage. 
     name: service
     x-tag-expanded: false
   - description:
-      These are used for onboard the organisation, organisation admin and
-      individual users to the system.  It also deals with all authentication and authorisation
-      APIs that can be configured towards external IDPs.
+      This consists of endpoints towards organisation admin to onboard to consent building block. 
+      It also deals with all authentication and authorisation APIs that can be configured 
+      towards external IDPs (e.g. using OpenID Connect).
     name: onboard
     x-tag-expanded: false

openapi/v2023.11.1/paths/auditAdminLogs.yaml

@@ -1,14 +1,14 @@
+summary: LIST - Fetch all organisational logs
+description: 
+  This endpoint is used to list all logs with pagination for an 
+  organisation defined in the consent building block.
 operationId: auditAdminLogs
-tags:
-  - audit
 security:
   - BearerAuth: []
 parameters:
   - $ref: "../parameters/offset.yaml"
   - $ref: "../parameters/limit.yaml"
   - $ref: "../parameters/logType.yaml"
-description: LIST - List all organisation admin logs
-summary: LIST - List all organisation admin logs
 responses:
   "200":
     content:
@@ -22,3 +22,6 @@ responses:
               type: array
             pagination:
               $ref: "../definitions/Pagination.yaml"
+tags:
+  - audit
+

openapi/v2023.11.1/paths/auditDataAgreementList.yaml

@@ -1,4 +1,7 @@
-description: LIST - Fetch all data agreements stored in the system
+summary: LIST - Fetch all data agreements
+description: 
+  This endpoint is used to fetch all data agreements defined
+  in the consent building block.
 operationId: auditDataAgreementList
 parameters:
   - $ref: "../parameters/offset.yaml"
@@ -21,10 +24,5 @@ responses:
     description: bad input parameter
 security:
   - BearerAuth: []
-summary: LIST - Fetch all data agreements stored in the system
 tags:
   - audit
-x-specification-crudl-model: ""
-x-specification-pii-or-sensitive: "False"
-x-specification-scenario: ""
-x-specification-usecase: UC-C-PIC-AT-001, UC-C-PIC-AT-003

openapi/v2023.11.1/paths/auditDataAgreementRecordRead.yaml

@@ -1,4 +1,7 @@
-description: READ - Fetch a single consent record
+summary: READ - Get consent record
+description: 
+  This endpoint is used to get a single consent record by ID in an 
+  organisation defined in the consent building block.
 operationId: auditConsentRecordRead
 parameters:
   - $ref: "../parameters/consentRecordId.yaml"
@@ -16,10 +19,5 @@ responses:
     description: bad input parameter
 security:
   - BearerAuth: []
-summary: READ - Fetch a single consent record
 tags:
   - audit
-x-specification-crudl-model: ""
-x-specification-pii-or-sensitive: "False"
-x-specification-scenario: ""
-x-specification-usecase: ""

openapi/v2023.11.1/paths/auditDataAgreementRecordsList.yaml

@@ -1,4 +1,7 @@
-description: LIST - Fetch all consent records
+summary: LIST - Fetch all consent records
+description: 
+  This endpoint is used to fetch all consent records with pagination 
+  for individuals in an organisation defined in the consent building block.
 operationId: auditDataAgreementRecordsList
 parameters:
   - $ref: "../parameters/offset.yaml"
@@ -25,10 +28,5 @@ responses:
     description: bad input parameter
 security:
   - BearerAuth: []
-summary: LIST - Fetch all consent records
 tags:
   - audit
-x-specification-crudl-model: ""
-x-specification-pii-or-sensitive: "False"
-x-specification-scenario: ""
-x-specification-usecase: UC-C-PIC-AT-003

openapi/v2023.11.1/paths/auditReadDataAgreement.yaml

@@ -1,4 +1,7 @@
-description: READ - Fetch a single data agreement.
+summary: READ - Get data agreement
+description: 
+  This endpoint is used to fetch a single data agreement for audit
+  purposes, for e.g., by an external third party.
 operationId: auditReadRecord
 parameters:
   - $ref: "../parameters/dataAgreementId.yaml"
@@ -16,10 +19,5 @@ responses:
     description: bad input parameter
 security:
   - BearerAuth: []
-summary: READ - Fetch a single data agreement.
 tags:
-  - audit
-x-specification-crudl-model: ""
-x-specification-pii-or-sensitive: "False"
-x-specification-scenario: ""
-x-specification-usecase: UC-C-PIC-AT-001, UC-C-PIC-AT-003
+  - audit

openapi/v2023.11.1/paths/configCreateAgreement.yaml

@@ -1,4 +1,4 @@
-summary: CREATE - Create a data agreement
+summary: CREATE - Create data agreement
 description: |
   This endpoint creates a data agreement for an organisation. 
   It also returns the latest revision of the created data agreement.
@@ -33,7 +33,3 @@ security:
   - BearerAuth: []
 tags:
   - config
-x-specification-crudl-model: DataAgreement
-x-specification-pii-or-sensitive: "False"
-x-specification-scenario: ""
-x-specification-usecase: UC-C-PIC-A-001

openapi/v2023.11.1/paths/configCreateApikey.yaml

@@ -1,4 +1,8 @@
-description: CREATE - Create an API key
+summary: CREATE - Create API key
+description: 
+  This endpoint is used to create an API key for accessing endpoints 
+  in the consent building block. It can created for a specific scope. 
+  E.g. Config, Onboard, Audit, Service.
 operationId: configCreateApikey
 parameters: []
 requestBody:
@@ -8,7 +12,7 @@ requestBody:
         properties:
           apiKey:
             $ref: ../definitions/ApiKey.yaml
-            description: An object of type ApiKey
+            description: An object of type APIKey
         required:
         - apiKey
         type: object
@@ -25,16 +29,10 @@ responses:
           required:
           - apiKey
           type: object
-    description: A set consisting of the new ApiKey object created, together with
-      the initial Revision object.
+    description: ""
   '400':
     description: bad input parameter
 security:
   - BearerAuth: []
-summary: CREATE - Create an API key
 tags:
-- config
-x-specification-crudl-model: ApiKey
-x-specification-pii-or-sensitive: 'False'
-x-specification-scenario: ''
-x-specification-usecase: UC-C-PIC-A-001
+- config

openapi/v2023.11.1/paths/configCreateIdp.yaml

@@ -1,4 +1,7 @@
-description: CREATE - Create an IDP
+summary: CREATE - Create IDP
+description: 
+  This endpoint is used to configure an IdP (e.g. OIDC based) used by 
+  the organisation in the consent building block.
 operationId: configCreateIdp
 parameters: []
 requestBody:
@@ -26,10 +29,5 @@ responses:
     description: bad input parameter
 security:
   - BearerAuth: []
-summary: CREATE - Create an IDP
 tags:
-  - config
-x-specification-crudl-model: IDP
-x-specification-pii-or-sensitive: "False"
-x-specification-scenario: ""
-x-specification-usecase: ""
+  - config

openapi/v2023.11.1/paths/configCreateIndividual.yaml

@@ -1,17 +1,11 @@
-tags:
-  - config
-summary: "CREATE - Create an individual"
+summary: CREATE - Create individual
+description: 
+  This endpoint creates an individual for an organisation in the 
+  consent block system. This is used to onboard existing or new users.
 operationId: "configCreatePolicy"
-description: "CREATE - Creates an Individual in the Consent system"
-parameters: []
-x-specification-usecase: ""
-x-specification-scenario: ""
-x-specification-pii-or-sensitive: "True"
-x-specification-crudl-model: "Individual"
 responses:
   "200":
     description: ""
-
     content:
       application/json:
         schema:
@@ -27,7 +21,6 @@ responses:
     description: bad input parameter
 security:
   - BearerAuth: []
-
 requestBody:
   content:
     application/json:
@@ -39,6 +32,7 @@ requestBody:
               - $ref: "../definitions/Individual.yaml"
               - $ref: "../definitions/IndividualExtras.yaml"
             description: An object of type Individual
-
         required:
           - individual
+tags:
+  - config

openapi/v2023.11.1/paths/configCreatePolicy.yaml

@@ -1,4 +1,7 @@
-description: CREATE - Create a new policy and returned together with revision
+summary: CREATE - Create data policy
+description:
+    This endpoint creates a new data policy that can be reused as global
+    parameter across all newly crearted data agremements. 
 operationId: configCreatePolicy
 parameters: []
 requestBody:
@@ -29,10 +32,5 @@ responses:
     description: bad input parameter
 security:
   - BearerAuth: []
-summary: CREATE - Create policy
 tags:
 - config
-x-specification-crudl-model: Policy
-x-specification-pii-or-sensitive: 'False'
-x-specification-scenario: ''
-x-specification-usecase: UC-C-PIC-A-001

openapi/v2023.11.1/paths/configCreateWebhook.yaml

@@ -1,8 +1,9 @@
-operationId: configCreateWebhook
+
 summary: CREATE - Create webhook
-description: Create webhook
-tags:
-  - config
+description: 
+  This endpoint is used to create a webhook to trigger events from 
+  consent building block to an external IT system. 
+operationId: configCreateWebhook
 requestBody:
   content:
     application/json:
@@ -25,3 +26,5 @@ responses:
 deprecated: false
 security:
   - BearerAuth: []
+tags:
+  - config

openapi/v2023.11.1/paths/configDeleteAgreement.yaml

@@ -1,4 +1,7 @@
-description: DELETE - Delete a data agreement
+summary: DELETE - Delete data agreement
+description: 
+  This endpoint allows the admin to delete all revisions of a chosen 
+  data agreement defined earlier in an organisation. 
 operationId: configDeleteAgreement
 parameters:
 - description: Unique ID of an object
@@ -18,10 +21,5 @@ responses:
     description: bad input parameter
 security:
   - BearerAuth: []
-summary: DELETE - Delete data agreement
 tags:
 - config
-x-specification-crudl-model: DataAgreement
-x-specification-pii-or-sensitive: 'False'
-x-specification-scenario: ''
-x-specification-usecase: UC-C-PIC-A-004

openapi/v2023.11.1/paths/configDeleteApiKey.yaml

@@ -1,5 +1,7 @@
-description: DELETE - Deletes an API key
-  DataAgreement.
+summary: DELETE - Delete API key
+description: 
+  This endpoint is used to delete an existing API key for  accessing 
+  endpoints in the consent building block.
 operationId: configDeletePolicy
 parameters:
   - $ref: "../parameters/apiKeyId.yaml"
@@ -16,10 +18,6 @@ responses:
     description: bad input parameter
 security:
   - BearerAuth: []
-summary: DELETE - Deletes an API key
 tags:
   - config
-x-specification-crudl-model: ApiKey
-x-specification-pii-or-sensitive: "False"
-x-specification-scenario: ""
-x-specification-usecase: UC-C-PIC-A-004
+x-specification-crudl-model: ApiK

openapi/v2023.11.1/paths/configDeletePolicy.yaml

@@ -1,6 +1,6 @@
-description: DELETE - Deletes an existing policy, returning the updated version
-  and a new revision. Deleting a policy is not possible if it's associated with active
-  DataAgreement.
+summary: DELETE - Delete data policy
+description:
+  This endpoint is used to delete an existing data policy.
 operationId: configDeletePolicy
 parameters:
   - description: Unique ID of an object
@@ -20,10 +20,5 @@ responses:
     description: bad input parameter
 security:
   - BearerAuth: []
-summary: DELETE - Deletes policy
 tags:
   - config
-x-specification-crudl-model: Policy
-x-specification-pii-or-sensitive: "False"
-x-specification-scenario: ""
-x-specification-usecase: UC-C-PIC-A-004

openapi/v2023.11.1/paths/configDeleteWebhook.yaml

@@ -1,8 +1,8 @@
-operationId: configDeleteWebhook
 summary: DELETE - Delete webhook
-description: Delete webhook
-tags:
-  - config
+description: 
+  This endpoint is used to delete an existing webhook that was defined 
+  to trigger events from the consent building block to an external IT system. 
+operationId: configDeleteWebhook
 parameters:
   - name: webhookId
     in: path
@@ -22,4 +22,6 @@ responses:
               $ref: "../definitions/Webhook.yaml"
 deprecated: false
 security:
-  - BearerAuth: []
+  - BearerAuth: []
+tags:
+  - config