fix(prism-agent): add consistency to documentation of OAS on DID endp…

…oints (#408) * docs(prism-agent): improve DID endpoints documentation * docs(prism-agent): clean up OAS examples and description * fix pr reviews
hyperledger · Mar 2, 2023 · dd04c3f · dd04c3f
1 parent b8e13d7
commit dd04c3f
Show file tree

Hide file tree

Showing 5 changed files with 45 additions and 43 deletions.
diff --git a/prism-agent/service/api/http/castor/parameters.yaml b/prism-agent/service/api/http/castor/parameters.yaml
@@ -7,6 +7,7 @@ components:
       description: DID reference.
       schema:
         type: string
+      example: did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff
     didOperationRefInPath:
       in: path
       name: didOperationRef

diff --git a/prism-agent/service/api/http/castor/schemas.yaml b/prism-agent/service/api/http/castor/schemas.yaml
@@ -28,10 +28,10 @@ components:
       properties:
         id:
           type: string
-          example: "did:prism:mainnet:123"
+          example: "did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff"
         controller:
           type: string
-          example: "did:prism:mainnet:456"
+          example: "did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff"
         verificationMethod:
           type: array
           items:
@@ -83,13 +83,13 @@ components:
       properties:
         id:
           type: string
-          example: "did:prism:123#key-1"
+          example: "did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff#key-1"
         type:
           type: string
           example: "EcdsaSecp256k1VerificationKey2019"
         controller:
           type: string
-          example: "did:prism:456"
+          example: "did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff"
         publicKeyJwk:
           $ref: "#/components/schemas/PublicKeyJwk"
 
@@ -111,7 +111,7 @@ components:
             - REFERENCED
         uri:
           type: string
-          example: did:example:123#key-1
+          example: did:prism:c7bd808e8e135236d7262ecf5e639b8f9d22bd886f59a4e6c909486846ca8319#key-1
         verificationMethod:
           $ref: "#/components/schemas/VerificationMethod"
 
@@ -139,13 +139,12 @@ components:
     CreateManagedDIDResponse:
       type: object
       required:
-        - did
         - longFormDid
       properties:
         longFormDid:
           type: string
           description: A long-form DID for the created DID
-          example: did:prism:1:abc123:abc123
+          example: did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff:Cr4BCrsBElsKBmF1dGgtMRAEQk8KCXNlY3AyNTZrMRIg0opTuxu-zt6aRbT1tPniG4eu4CYsQPM3rrLzvzNiNgwaIIFTnyT2N4U7qCQ78qtWC3-p0el6Hvv8qxG5uuEw-WgMElwKB21hc3RlcjAQAUJPCglzZWNwMjU2azESIKhBU0eCOO6Vinz_8vhtFSAhYYqrkEXC8PHGxkuIUev8GiAydFHLXb7c22A1Uj_PR21NZp6BCDQqNq2xd244txRgsQ
 
     UpdateManagedDIDRequest:
       type: object
@@ -154,6 +153,10 @@ components:
       properties:
         actions:
           type: array
+          description: |
+            A list of actions to perform on DID document.
+            The field `addKey`, `removeKey`, `addService`, `removeService`, `updateService` must corresponds to
+            the `actionType` specified. For example, `addKey` must be present when `actionType` is `ADD_KEY`.
           items:
             type: object
             description: Detail of DID update action. Only property matching actionType can be present.
@@ -179,7 +182,7 @@ components:
                   id:
                     type: string
                     description: ID of key to remove from DID document
-                    example: key1
+                    example: key-1
               addService:
                 $ref: "#/components/schemas/Service"
               removeService:
@@ -190,7 +193,7 @@ components:
                   id:
                     type: string
                     description: ID of service to remove from DID document
-                    example: service1
+                    example: service-1
               updateService:
                 type: object
                 description: A patch to existing Service. 'type' and 'serviceEndpoint' must not be both empty.
@@ -200,7 +203,7 @@ components:
                   id:
                     type: string
                     description: ID of existing service to update in the DID document
-                    example: service1
+                    example: service-1
                   type:
                     type: string
                     enum:
@@ -242,14 +245,16 @@ components:
       properties:
         did:
           type: string
-          example: did:prism:abc
+          example: did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff
         longFormDid:
           type: string
           description: A long-form DID. Mandatory when status is not PUBLISHED and optional when status is PUBLISHED
-          example: did:prism:abc:123
+          example: did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff:Cr4BCrsBElsKBmF1dGgtMRAEQk8KCXNlY3AyNTZrMRIg0opTuxu-zt6aRbT1tPniG4eu4CYsQPM3rrLzvzNiNgwaIIFTnyT2N4U7qCQ78qtWC3-p0el6Hvv8qxG5uuEw-WgMElwKB21hc3RlcjAQAUJPCglzZWNwMjU2azESIKhBU0eCOO6Vinz_8vhtFSAhYYqrkEXC8PHGxkuIUev8GiAydFHLXb7c22A1Uj_PR21NZp6BCDQqNq2xd244txRgsQ
         status:
           type: string
-          description: A status indicating whether this is already published from the wallet or not. Does not represent DID full lifecyle (e.g. deactivated, recovered, updated).
+          description: |
+            A status indicating a publication state of a DID in the wallet (e.g. PUBLICATION_PENDING, PUBLISHED).
+            Does not represent DID a full lifecyle (e.g. deactivated, recovered, updated).
           enum:
             - CREATED
             - PUBLICATION_PENDING
@@ -272,9 +277,6 @@ components:
         kty:
           type: string
           example: "EC"
-        kid:
-          type: string
-          example: "_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw"
 
     Service:
       type: object
@@ -285,7 +287,7 @@ components:
       properties:
         id:
           type: string
-          example: "service1"
+          example: "service-1"
         type:
           type: string
           enum:
@@ -307,7 +309,7 @@ components:
         id:
           type: string
           description: Identifier of a verification material in the DID Document
-          example: key1
+          example: key-1
         purpose:
           type: string
           enum:
@@ -331,10 +333,10 @@ components:
       properties:
         id:
           type: string
-          example: "123"
+          example: 98e6a4db10e58fcc011dd8def5ce99fd8b52af39e61e5fb436dc28259139818b
         didRef:
           type: string
-          example: "did:prism:123"
+          example: did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff
 
     ErrorResponse:
       type: object

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,7 +1,7 @@
 ---
 openapi: 3.0.1
 info:
-  title: PrismAgent OpenAPI specification
+  title: Prism Agent OpenAPI specification
   description: OpenAPI specification for Decentralized Identifiers (DID) Operations
   version: 0.41.0
   contact:
@@ -22,9 +22,9 @@ security:
 tags:
   # Castor
   - name: DID
-    description: Generic DID Endpoints
+    description: DID REST API
   - name: DID Registrar
-    description: DID Endpoints where keys are managed by PrismAgent
+    description: DID Registrar REST API (Prism Agent managed DID)
   # Pollux
   - name: Schema Registry
     description: Schema Registry REST API
@@ -45,7 +45,7 @@ paths:
       tags: ["DID"]
       operationId: getDid
       summary: Resolve Prism DID
-      description: Resolve Prism DID
+      description: Resolve Prism DID to a DID document.
       parameters:
         - $ref: "./castor/parameters.yaml#/components/parameters/didRefInPath"
       responses:
@@ -66,17 +66,17 @@ paths:
     get:
       tags: ["DID Registrar"]
       operationId: listManagedDid
-      summary: List all DIDs stored in PrismAgent's wallet
+      summary: List all DIDs stored in Prism Agent's wallet
       description: |
-        List all DIDs stored in PrismAgent's wallet.
+        List all DIDs stored in Prism Agent's wallet.
         Return a paginated items ordered by created timestamp.
         If the `limit` parameter is not set, it defaults to 100 items per page.
       parameters:
         - $ref: ./shared/parameters.yaml#/components/parameters/offset
         - $ref: ./shared/parameters.yaml#/components/parameters/limit
       responses:
         "200":
-          description: List PrismAgent managed DIDs
+          description: List Prism Agent managed DIDs
           content:
             application/json:
               schema:
@@ -91,10 +91,10 @@ paths:
     post:
       tags: ["DID Registrar"]
       operationId: createManagedDid
-      summary: Create unpublished DID and store it in PrismAgent's wallet
+      summary: Create unpublished DID and store it in Prism Agent's wallet
       description: |
-        Create unpublished DID and store it inside PrismAgent's wallet. The private keys of the DID is
-        managed by PrismAgent. The DID can later be published to the VDR using publications endpoint.
+        Create unpublished DID and store it inside Prism Agent's wallet. The private keys of the DID is
+        managed by Prism Agent. The DID can later be published to the VDR using publications endpoint.
       requestBody:
         required: true
         content:
@@ -119,13 +119,13 @@ paths:
     get:
       tags: ["DID Registrar"]
       operationId: getManagedDid
-      summary: Get DID stored in PrismAgent's wallet
-      description: Get DID stored in PrismAgent's wallet
+      summary: Get DID stored in Prism Agent's wallet
+      description: Get DID stored in Prism Agent's wallet
       parameters:
         - $ref: "./castor/parameters.yaml#/components/parameters/didRefInPath"
       responses:
         "200":
-          description: Get PrismAgent managed DID
+          description: Get Prism Agent managed DID
           content:
             application/json:
               schema:
@@ -141,9 +141,9 @@ paths:
     post:
       tags: ["DID Registrar"]
       operationId: publishManagedDid
-      summary: Publish the DID stored in PrismAgent's wallet to the VDR
+      summary: Publish the DID stored in Prism Agent's wallet to the VDR
       description: |
-        Publish the DID stored in PrismAgent's wallet to the VDR.
+        Publish the DID stored in Prism Agent's wallet to the VDR.
       parameters:
         - $ref: "./castor/parameters.yaml#/components/parameters/didRefInPath"
       responses:
@@ -164,12 +164,12 @@ paths:
     post:
       tags: ["DID Registrar"]
       operationId: updateManagedDid
-      summary: Update DID in PrismAgent's wallet and post update operation to the VDR
+      summary: Update DID in Prism Agent's wallet and post update operation to the VDR
       description: |
-        Update DID in PrismAgent's wallet and post update operation to the VDR.
-        This endpoint updates the DID document from last confirmed operation.
+        Update DID in Prism Agent's wallet and post update operation to the VDR.
+        This endpoint updates the DID document from the last confirmed operation.
         Submitting multiple update operations without waiting for confirmation will result in
-        some operation being rejected as only one operation can be appended from last confirmed operation.
+        some operations being rejected as only one operation is allowed to be appended to the last confirmed operation.
       requestBody:
         required: true
         content:
@@ -196,9 +196,9 @@ paths:
     post:
       tags: ["DID Registrar"]
       operationId: deactivateManagedDid
-      summary: Deactivate DID in PrismAgent's wallet and post deactivate operation to blockchain
+      summary: Deactivate DID in Prism Agent's wallet and post deactivate operation to the VDR
       description: |
-        Deactivate DID in PrismAgent's wallet and post deactivate operation to blockchain.
+        Deactivate DID in Prism Agent's wallet and post deactivate operation to the VDR.
       parameters:
         - $ref: "./castor/parameters.yaml#/components/parameters/didRefInPath"
       responses:

diff --git a/...ervice/server/src/main/scala/io/iohk/atala/agent/server/http/marshaller/JsonSupport.scala b/...ervice/server/src/main/scala/io/iohk/atala/agent/server/http/marshaller/JsonSupport.scala
@@ -33,7 +33,7 @@ trait JsonSupport extends SprayJsonSupport with DefaultJsonProtocol {
   given RootJsonFormat[ManagedDID] = jsonFormat3(ManagedDID.apply)
   given RootJsonFormat[ManagedDIDPage] = jsonFormat6(ManagedDIDPage.apply)
   given RootJsonFormat[ManagedDIDKeyTemplate] = jsonFormat2(ManagedDIDKeyTemplate.apply)
-  given RootJsonFormat[PublicKeyJwk] = jsonFormat5(PublicKeyJwk.apply)
+  given RootJsonFormat[PublicKeyJwk] = jsonFormat4(PublicKeyJwk.apply)
   given RootJsonFormat[Service] = jsonFormat3(Service.apply)
   given RootJsonFormat[UpdateManagedDIDRequest] = jsonFormat1(UpdateManagedDIDRequest.apply)
   given RootJsonFormat[UpdateManagedDIDRequestActionsInner] = jsonFormat6(UpdateManagedDIDRequestActionsInner.apply)

diff --git a/...ce/server/src/main/scala/io/iohk/atala/agent/server/http/model/OASDomainModelHelper.scala b/...ce/server/src/main/scala/io/iohk/atala/agent/server/http/model/OASDomainModelHelper.scala
@@ -292,7 +292,6 @@ trait OASDomainModelHelper {
         x = Some(publicKeyJwk.x),
         y = Some(publicKeyJwk.y),
         kty = publicKeyJwk.kty,
-        kid = None
       )
     }
   }