docs(prism-agent): improve OAS documentation for connect and issue.

prism-agent/service/api/http/connect/schemas.yaml

@@ -5,27 +5,31 @@ components:
       in: path
       name: connectionId
       required: true
-      description: the unique identifier of the connection record
+      description: The unique identifier of the connection record.
       schema:
         type: string
   schemas:
     CreateConnectionRequest:
       type: object
       properties:
         label:
+          description: A human readable alias for the connection.
           type: string
           example: "Peter"
 
     AcceptConnectionInvitationRequest:
+      description: The request used by an invitee to accept a connection invitation received from an inviter, using out-of-band mechanism.
       type: object
       required:
         - invitation
       properties:
         invitation:
+          description: The base64-encoded raw invitation.
           type: string
           example: "eyJAaWQiOiIzZmE4NWY2NC01NzE3LTQ1NjItYjNmYy0yYzk2M2Y2NmFmYTYiLCJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvbXktZmFtaWx5LzEuMC9teS1tZXNzYWdlLXR5cGUiLCJkaWQiOiJXZ1d4cXp0ck5vb0c5MlJYdnhTVFd2IiwiaW1hZ2VVcmwiOiJodHRwOi8vMTkyLjE2OC41Ni4xMDEvaW1nL2xvZ28uanBnIiwibGFiZWwiOiJCb2IiLCJyZWNpcGllbnRLZXlzIjpbIkgzQzJBVnZMTXY2Z21NTmFtM3VWQWpacGZrY0pDd0R3blpuNnozd1htcVBWIl0sInJvdXRpbmdLZXlzIjpbIkgzQzJBVnZMTXY2Z21NTmFtM3VWQWpacGZrY0pDd0R3blpuNnozd1htcVBWIl0sInNlcnZpY2VFbmRwb2ludCI6Imh0dHA6Ly8xOTIuMTY4LjU2LjEwMTo4MDIwIn0="
 
     Connection:
+      description: A connection record.
       type: object
       allOf:
         - $ref: "#/components/schemas/CreateConnectionRequest"
@@ -39,67 +43,78 @@ components:
             - invitation
           properties:
             self:
+              description: The reference to the connection resource.
               type: string
               example: https://atala-prism-products.io/connections/ABCD-1234
             kind:
+              description: The type of object returned. In this case a `Connection`.
               type: string
-              example: ConnectionState
+              example: Connection
             connectionId:
+              description: The unique identifier of the connection.
               type: string
               format: uuid
-              example: "12345-9876"
+              example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
             myDid:
+              description: The DID representing me as the inviter or invitee in this specific connection.
               type: string
-              example: "did:prism:12345"
+              example: "did:peer:12345"
             theirDid:
+              description: The DID representing the other peer as the an inviter or invitee in this specific connection.
               type: string
-              example: "did:peer:12345"
+              example: "did:peer:67890"
             state:
+              description: The current state of the connection protocol execution.
               type: string
               enum:
-                [
-                  "InvitationGenerated",
-                  "InvitationReceived",
-                  "ConnectionRequestPending",
-                  "ConnectionRequestSent",
-                  "ConnectionRequestReceived",
-                  "ConnectionResponsePending",
-                  "ConnectionResponseSent",
-                  "ConnectionResponseReceived",
-                  "ProblemReportPending",
-                  "ProblemReportSent",
-                  "ProblemReportReceived",
-                ]
+                - InvitationGenerated
+                - InvitationReceived
+                - ConnectionRequestPending
+                - ConnectionRequestSent
+                - ConnectionRequestReceived
+                - ConnectionResponsePending
+                - ConnectionResponseSent
+                - ConnectionResponseReceived
+                - ProblemReportPending
+                - ProblemReportSent
+                - ProblemReportReceived
             createdAt:
+              description: The date and time the connection record was created.
               type: string
               format: date-time
               example: 2021-10-31T09:22:23Z
             updatedAt:
+              description: The date and time the connection record was last updated.
               type: string
               format: date-time
               example: 2021-12-31T13:59:60Z
             invitation:
               $ref: "#/components/schemas/ConnectionInvitation"
 
     ConnectionCollection:
+      description: A collection of connection records.
       type: object
       required:
         - self
         - kind
         - contents
       properties:
         self:
+          description: The reference to the connection collection itself.
           type: string
           example: https://atala-prism-products.io/connections
         kind:
+          description: The type of object returned. In this case a `Collection`.
           type: string
           example: Collection
         contents:
+          description: The array containing the list of connection records.
           type: array
           items:
             $ref: "#/components/schemas/Connection"
 
     ConnectionInvitation:
+      description: A connection invitation.
       type: object
       required:
         - id

prism-agent/service/api/http/pollux/parameters.yaml

@@ -4,7 +4,7 @@ components:
       in: path
       name: recordId
       required: true
-      description: The issue credential record Id.
+      description: The unique identifier of the issue credential record.
       schema:
         type: string
         format: uuid

prism-agent/service/api/http/pollux/schemas.yaml

@@ -236,29 +236,32 @@ components:
       properties:
         schemaId:
           type: string
-          description: Identifier of the VC Schema associated with this object
+          description: The unique identifier of the schema used for this credential offer.
         subjectId:
           type: string
-          description: Subject DID of the verifiable credentials object
+          description: The identifier (e.g DID) of the subject to which the verifiable credential will be issued.
           example: did:prism:subjectofverifiablecredentials
         validityPeriod:
           type: number
-          description: The validity period in seconds of the verifiable credential
+          description: The validity period in seconds of the verifiable credential that will be issued.
           example: 3600
         claims:
           type: object
-          description: Claims that will be associated with given verifiable credentials
+          description: The claims that will be associated with the issued verifiable credential.
           additionalProperties:
             type: string
         automaticIssuance:
+          description: |
+            Specifies whether or not the credential should be automatically generated and issued when receiving the `CredentialRequest` from the holder.
+            If set to `false`, a manual approval by the issuer via API call will be required for the VC to be issued.
           type: boolean
           default: true
         awaitConfirmation:
           type: boolean
           default: true
 
     CreateIssueCredentialRecordRequest:
-      description: A request to create a new "issue credential record"
+      description: A request to create a new "issue credential record".
       type: object
       allOf:
         - $ref: "#/components/schemas/IssueCredentialRecordBase"
@@ -269,14 +272,14 @@ components:
           properties:
             issuingDID:
               type: string
-              description: Issuer DID of the verifiable credentials object
+              description: The issuer DID of the verifiable credential object.
               example: did:prism:issuerofverifiablecredentials
             connectionId:
               type: string
-              description: A connection ID between issuer and holder.
+              description: The unique identifier of a DIDComm connection that already exists between the issuer and the holder, and that will be used to execute the issue credential protocol.
 
     IssueCredentialRecord:
-      description: An issue credential record to store the state of the protocol execution
+      description: An issue credential record that stores the state of the protocol execution.
       type: object
       allOf:
         - $ref: "#/components/schemas/IssueCredentialRecordBase"
@@ -288,20 +291,25 @@ components:
             - protocolState
           properties:
             recordId:
+              description: The unique identifier of the issue credential record.
               type: string
               format: uuid
             createdAt:
+              description: The date and time when the issue credential record was created.
               type: string
               format: date-time
             updatedAt:
+              description: The date and time when the issue credential record was last updated.
               type: string
               format: date-time
             role:
+              description: The role played by the Prism agent in the credential issuance flow.
               type: string
               enum:
                 - Issuer
                 - Holder
             protocolState:
+              description: The current state of the issue credential protocol execution.
               type: string
               enum:
                 - OfferPending
@@ -323,21 +331,23 @@ components:
                 - PublicationQueued
                 - Published
             jwtCredential:
+              description: The base64-encoded JWT verifiable credential that has been sent by the issuer.
               type: string
             issuingDID:
               type: string
-              description: Issuer DID of the verifiable credentials object
+              description: Issuer DID of the verifiable credential object.
               example: did:prism:issuerofverifiablecredentials
 
     IssueCredentialRecordCollection:
-      description: A collection of issue credential records
+      description: A collection of issue credential records.
       required:
         - items
         - offset
         - limit
         - count
       properties:
         items:
+          description: The array containing the list of issue credential records.
           type: array
           items:
             $ref: "#/components/schemas/IssueCredentialRecord"