docs(prism-agent): update schemas.yams and fix yamllint errors, add l…

…inting changelog (#237) Co-authored-by: Rodolfo Miranda <you@example.com>
hyperledger · Feb 15, 2023 · bb78688 · bb78688
1 parent 174b4aa
commit bb78688
Show file tree

Hide file tree

Showing 5 changed files with 75 additions and 20 deletions.
diff --git a/.yamllint.yml b/.yamllint.yml
@@ -0,0 +1,17 @@
+---
+###########################################
+# These are the rules used for            #
+# linting all the yaml files in the stack #
+# NOTE:                                   #
+# You can disable line with:              #
+# # yamllint disable-line                 #
+###########################################
+extends: default
+rules:
+  new-lines:
+    level: warning
+    type: unix
+  line-length:
+    max: 600
+  comments:
+    min-spaces-from-content: 1 # Used to follow prettier standard: https://github.com/prettier/prettier/pull/10926
diff --git a/docs/guides/linting.md b/docs/guides/linting.md
@@ -81,6 +81,26 @@ Insert suggestion / description of what it did well, what it didn't do well and
 
 ## Changelog
 
+---
+#### YAMLLINT checker configuration file is added explicitly and rule line-length is set to 600
+Date Added: 2023-02-15
+
+Author: Yurii Shynbuiev
+
+Date Actioned: 2023-02-15
+
+Linter - Current Status: Enabled
+
+Linter - Suggested Change: Customise
+
+*Change detail*
+
+yamllint checker reports the error for OAS files for lines longer than 500 characters.
+
+The configuration file for the yamllint checker was added to the root of the project `.yamllint.yml`.
+
+The rule for the line-length was set to 600
+
 ---
 #### BASH_SHELLCHECK_DISABLE_ERRORS
 

diff --git a/prism-agent/service/api/http/connect/schemas.yaml b/prism-agent/service/api/http/connect/schemas.yaml
@@ -1,10 +1,11 @@
+---
 components:
   parameters:
     connectionId:
       in: path
       name: connectionId
       required: true
-      description: Id of connection state record.
+      description: the unique identifier of the connection record
       schema:
         type: string
   schemas:
@@ -55,7 +56,20 @@ components:
               example: "did:peer:12345"
             state:
               type: string
-              enum: ["pending", "success", "failed"]
+              enum:
+                [
+                  "InvitationGenerated",
+                  "InvitationReceived",
+                  "ConnectionRequestPending",
+                  "ConnectionRequestSent",
+                  "ConnectionRequestReceived",
+                  "ConnectionResponsePending",
+                  "ConnectionResponseSent",
+                  "ConnectionResponseReceived",
+                  "ProblemReportPending",
+                  "ProblemReportSent",
+                  "ProblemReportReceived",
+                ]
             createdAt:
               type: string
               format: date-time
@@ -96,19 +110,19 @@ components:
         id:
           type: string
           format: uuid
-          description: The invitation identifier used as parent thread ID (pthid) for the response message that follows.
+          description: The unique identifier of the invitation. It should be used as parent thread ID (pthid) for the Connection Request message that follows.
           example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
         type:
           type: string
-          description: The DIDComm Message Type URI (MTURI) the invitation message coplies with.
+          description: The DIDComm Message Type URI (MTURI) the invitation message complies with.
           example: "https://didcomm.org/out-of-band/2.0/invitation"
         from:
           type: string
           description: The DID representing the sender to be used by recipients for future interactions.
-          example: "did:prism:1234457"
+          example: "did:peer:1234457"
         invitationUrl:
           type: string
-          description: The invitation message encoded as a URL.
+          description: The invitation message encoded as a URL. This URL follows the Out of [Band 2.0 protocol](https://identity.foundation/didcomm-messaging/spec/v2.0/#out-of-band-messages) and can be used to generate a QR code for example.
           example: https://domain.com/path?_oob=eyJAaWQiOiIzZmE4NWY2NC01NzE3LTQ1NjItYjNmYy0yYzk2M2Y2NmFmYTYiLCJAdHlwZSI6Imh0dHBzOi8vZGlkY29tbS5vcmcvbXktZmFtaWx5LzEuMC9teS1tZXNzYWdlLXR5cGUiLCJkaWQiOiJXZ1d4cXp0ck5vb0c5MlJYdnhTVFd2IiwiaW1hZ2VVcmwiOiJodHRwOi8vMTkyLjE2OC41Ni4xMDEvaW1nL2xvZ28uanBnIiwibGFiZWwiOiJCb2IiLCJyZWNpcGllbnRLZXlzIjpbIkgzQzJBVnZMTXY2Z21NTmFtM3VWQWpacGZrY0pDd0R3blpuNnozd1htcVBWIl0sInJvdXRpbmdLZXlzIjpbIkgzQzJBVnZMTXY2Z21NTmFtM3VWQWpacGZrY0pDd0R3blpuNnozd1htcVBWIl0sInNlcnZpY2VFbmRwb2ludCI6Imh0dHA6Ly8xOTIuMTY4LjU2LjEwMTo4MDIwIn0=
 
     ErrorResponse:

diff --git a/prism-agent/service/api/http/pollux/schemas.yaml b/prism-agent/service/api/http/pollux/schemas.yaml
@@ -1,3 +1,4 @@
+---
 components:
   schemas:
     # Common
@@ -667,7 +668,7 @@ components:
           type: string
           description: if present, MUST be set to JWT
         kid:
-          type: string #TODO: clarify the better type for DID key id
+          type: string # TODO: clarify the better type for DID key id
           description: -|
             MAY be used if there are multiple keys associated with the issuer of the JWT.
             The key discovery is out of the scope of this specification.
@@ -682,7 +683,7 @@ components:
         exp:
           type: string
           description: MUST represent the expirationDate property, encoded as a UNIX timestamp (NumericDate).
-          example: "2022-07-12T16:51:22.000Z" #TODO: exp field is required according to the spec, but looks like it's not required in VC data model
+          example: "2022-07-12T16:51:22.000Z" # TODO: exp field is required according to the spec, but looks like it's not required in VC data model
         iss:
           type: string
           description: -|

diff --git a/prism-agent/service/api/http/prism-agent-openapi-spec.yaml b/prism-agent/service/api/http/prism-agent-openapi-spec.yaml
@@ -1,3 +1,4 @@
+---
 openapi: 3.0.1
 info:
   title: PrismAgent OpenAPI specification
@@ -33,7 +34,7 @@ tags:
     description: Present Proof REST API
   # Connect
   - name: Connections Management
-    description: API for driving connection process.
+    description: Manage [DIDComm v2](https://identity.foundation/didcomm-messaging/spec/v2.0/) connections
 
 paths:
   # ----------------------------------
@@ -828,12 +829,11 @@ paths:
     post:
       tags: ["Connections Management"]
       operationId: createConnection
-      summary: Creates new connection and returns an invitation.
-      description: |-
-        Returns new invitation object and creates new connection state record in `pending` state.
-        Content of invitation depends on DIDComm protocol used, here is an example of how it would look like for `AIP 1.0 connection/v1` protocol.
-        Once connection invitation is accepted, Agent should filter all additional attempts to accept it.
-        We consider mult-party connections as out of scope for now.
+      summary: Creates a new connection record and returns an Out of Band invitation
+      description: |
+        Generates a new Peer DID and creates an [Out of Band 2.0](https://identity.foundation/didcomm-messaging/spec/v2.0/#out-of-band-messages) invitation.
+        It returns a new connection record in `InvitationGenerated` state.
+        The request body may contain a `label` that can be used as a human readable alias for the connection, for example `{'label': "Bob"}`
       requestBody:
         required: true
         content:
@@ -858,10 +858,10 @@ paths:
     get:
       tags: ["Connections Management"]
       operationId: getConnections
-      summary: Returns a list of connections.
+      summary: Returns the list of connection records
       responses:
         "200":
-          description: List of connection state objects
+          description: List of connection records
           content:
             application/json:
               schema:
@@ -879,7 +879,7 @@ paths:
       parameters:
         - $ref: "./connect/schemas.yaml#/components/parameters/connectionId"
       operationId: getConnection
-      summary: Returns an existing connection record by id.
+      summary: Returns an existing connection record by its Id
       responses:
         "200":
           description: Connection state record
@@ -898,8 +898,11 @@ paths:
     post:
       tags: ["Connections Management"]
       operationId: acceptConnectionInvitation
-      summary: Accepts externally received invitation.
-      description: Creates new connection state record in `pending` state. It is assumed that application would first decode and validate the invitation. When it is accepted in the application side, it should be submitted in raw format to this API.
+      summary: Accepts an Out of Band invitation
+      description: |
+        Accepts an [Out of Band 2.0](https://identity.foundation/didcomm-messaging/spec/v2.0/#out-of-band-messages) invitation, generates a new Peer DID,
+        and submits a Connection Request to the inviter.
+        It returns a connection object in `ConnectionRequestPending` state, until the Connection Request is eventually sent to the inviter by the prism-agent's background process. The connection object state will then automatically move to `ConnectionRequestSent`.
       requestBody:
         required: true
         content: