fix: VC Verification API Doc (#1118)

Signed-off-by: Bassam Riman <[email protected]> Co-authored-by: Yurii Shynbuiev - IOHK <[email protected]> Signed-off-by: Pat Losoponkul <[email protected]>
hyperledger · Jun 13, 2024 · 8be5e48 · 8be5e48
1 parent 4331fd2
commit 8be5e48
Show file tree

Hide file tree

Showing 7 changed files with 91 additions and 26 deletions.
diff --git a/.../main/scala/org/hyperledger/identus/verification/controller/VcVerificationEndpoints.scala b/.../main/scala/org/hyperledger/identus/verification/controller/VcVerificationEndpoints.scala
@@ -21,14 +21,14 @@ object VcVerificationEndpoints {
     endpoint.post
       .tag("Verifiable Credentials Verification")
       .name("verify")
-      .summary("As a Verifier, verify a set of credentials")
-      .description("As a Verifier, verify a set of credentials")
+      .summary("Verify a set of credentials as a Verifier")
+      .description("Endpoint to verify a set of verifiable credentials as a Verifier.")
       .securityIn(apiKeyHeader)
       .securityIn(jwtAuthHeader)
       .in("verification" / "credential")
       .in(extractFromRequest[RequestContext](RequestContext.apply))
-      .in(jsonBody[List[http.VcVerificationRequest]].description("List of VC to verify"))
-      .out(statusCode(StatusCode.Ok).description("List of VC verification outcome"))
+      .in(jsonBody[List[http.VcVerificationRequest]].description("List of verifiable credentials to verify"))
+      .out(statusCode(StatusCode.Ok).description("List of verifiable credentials verification outcomes"))
       .out(jsonBody[List[http.VcVerificationResponse]])
       .errorOut(basicFailuresAndForbidden)
 }
diff --git a/.../org/hyperledger/identus/verification/controller/http/ParameterizableVcVerification.scala b/.../org/hyperledger/identus/verification/controller/http/ParameterizableVcVerification.scala
@@ -1,12 +1,23 @@
 package org.hyperledger.identus.verification.controller.http
 
 import sttp.tapir.Schema
+import sttp.tapir.Schema.annotations.{description, encodedExample}
 import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder}
 
+/** Represents a parameterizable verification to be performed on a verifiable credential.
+  *
+  * @param verification
+  *   The type of verification to perform.
+  * @param parameter
+  *   Optional parameter for the verification.
+  */
 final case class ParameterizableVcVerification(
+    @description("The type of verification to perform.")
     verification: VcVerification,
+    @description("Optional parameter for the verification.")
     parameter: Option[VcVerificationParameter]
 )
+
 object ParameterizableVcVerification {
   given encoder: JsonEncoder[ParameterizableVcVerification] =
     DeriveJsonEncoder.gen[ParameterizableVcVerification]

diff --git a/.../src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerification.scala b/.../src/main/scala/org/hyperledger/identus/verification/controller/http/VcVerification.scala
@@ -4,22 +4,36 @@ import org.hyperledger.identus.api.http.ErrorResponse
 import org.hyperledger.identus.pollux.core.service
 import org.hyperledger.identus.pollux.core.service.verification.VcVerification as ServiceVcVerification
 import sttp.tapir.Schema
+import sttp.tapir.Schema.annotations.description
 import zio.{IO, *}
 import zio.json.{JsonDecoder, JsonEncoder}
 
+/** Enum representing the various types of verifications that can be performed on a verifiable credential.
+  */
 enum VcVerification {
-  case SignatureVerification
-  case IssuerIdentification
-  case ExpirationCheck
-  case NotBeforeCheck
-  case AudienceCheck
-  case SubjectVerification
-  case IntegrityOfClaims
-  case ComplianceWithStandards
-  case RevocationCheck
-  case AlgorithmVerification
-  case SchemaCheck
-  case SemanticCheckOfClaims
+  @description("Verify the digital signature of the credential.") case SignatureVerification
+
+  @description("Verify the identity of the issuer of the credential.") case IssuerIdentification
+
+  @description("Check if the credential has expired.") case ExpirationCheck
+
+  @description("Check if the credential is valid before a certain date and time.") case NotBeforeCheck
+
+  @description("Verify the audience for which the credential is intended.") case AudienceCheck
+
+  @description("Verify the subject of the credential.") case SubjectVerification
+
+  @description("Check the integrity of the claims in the credential.") case IntegrityOfClaims
+
+  @description("Ensure the credential complies with required standards.") case ComplianceWithStandards
+
+  @description("Check if the credential has been revoked.") case RevocationCheck
+
+  @description("Verify the algorithm used for creating the credential.") case AlgorithmVerification
+
+  @description("Validate the schema of the credential.") case SchemaCheck
+
+  @description("Perform a semantic check on the claims of the credential.") case SemanticCheckOfClaims
 }
 
 object VcVerification {

diff --git a/.../scala/org/hyperledger/identus/verification/controller/http/VcVerificationParameter.scala b/.../scala/org/hyperledger/identus/verification/controller/http/VcVerificationParameter.scala
@@ -1,10 +1,16 @@
 package org.hyperledger.identus.verification.controller.http
 
 import sttp.tapir.Schema
+import sttp.tapir.Schema.annotations.{description, encodedExample}
 import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder}
 
 import java.time.OffsetDateTime
 
+/** Base trait for verification parameters.
+  *
+  * @param parameterType
+  *   The type of the parameter.
+  */
 sealed trait VcVerificationParameter(val parameterType: String)
 
 object VcVerificationParameter {
@@ -31,7 +37,16 @@ object VcVerificationParameter {
 
 }
 
-case class DidParameter(did: String) extends VcVerificationParameter("DidParameter")
+/** Parameter for DID-based verifications.
+  *
+  * @param did
+  *   The DID (Decentralized Identifier) to use for verification.
+  */
+case class DidParameter(
+    @description("The DID (Decentralized Identifier) to use for verification.")
+    @encodedExample("did:prism:issuer")
+    did: String
+) extends VcVerificationParameter("DidParameter")
 
 object DidParameter {
   given encoder: JsonEncoder[DidParameter] =
@@ -43,7 +58,16 @@ object DidParameter {
   given schema: Schema[DidParameter] = Schema.derived
 }
 
-case class DateTimeParameter(dateTime: OffsetDateTime) extends VcVerificationParameter("DateTimeParameter")
+/** Parameter for date-time based verifications.
+  *
+  * @param dateTime
+  *   The date and time to use for verification.
+  */
+case class DateTimeParameter(
+    @description("The date and time to use for verification.")
+    @encodedExample("2022-03-10T12:00:00Z")
+    dateTime: OffsetDateTime
+) extends VcVerificationParameter("DateTimeParameter")
 
 object DateTimeParameter {
   given encoder: JsonEncoder[DateTimeParameter] =

diff --git a/...in/scala/org/hyperledger/identus/verification/controller/http/VcVerificationRequest.scala b/...in/scala/org/hyperledger/identus/verification/controller/http/VcVerificationRequest.scala
@@ -5,7 +5,10 @@ import org.hyperledger.identus.pollux.core.service.verification.VcVerificationRe
 import sttp.tapir.Schema
 import sttp.tapir.Schema.annotations.{description, encodedExample}
 import zio.{IO, *}
+import zio.json.*
 import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder}
+import zio.json.ast.Json
+import zio.json.ast.Json.*
 
 import java.time.OffsetDateTime
 
@@ -29,8 +32,9 @@ object VcVerificationRequest {
         )
 
     object parameterizableVcVerifications
-        extends Annotation[List[ParameterizableVcVerification]](
-          description = "The list of Verifications to verify. All verifications run if Verifications left empty",
+        extends Annotation[String](
+          description =
+            "The list of verifications to perform on the credential. If the list is empty, all available verifications will be performed.",
           example = List(
             ParameterizableVcVerification(VcVerification.SignatureVerification, None),
             ParameterizableVcVerification(VcVerification.IssuerIdentification, Some(DidParameter("did:prism:issuer"))),
@@ -50,7 +54,7 @@ object VcVerificationRequest {
             ParameterizableVcVerification(VcVerification.AlgorithmVerification, None),
             ParameterizableVcVerification(VcVerification.SchemaCheck, None),
             ParameterizableVcVerification(VcVerification.SemanticCheckOfClaims, None)
-          )
+          ).toJson
         )
   }
 

diff --git a/...n/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResponse.scala b/...n/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResponse.scala
@@ -3,7 +3,9 @@ package org.hyperledger.identus.verification.controller.http
 import org.hyperledger.identus.api.http.Annotation
 import sttp.tapir.Schema
 import sttp.tapir.Schema.annotations.{description, encodedExample}
-import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder}
+import zio.json.*
+import zio.json.ast.Json
+import zio.json.ast.Json.*
 
 final case class VcVerificationResponse(
     @description(VcVerificationResponse.annotations.credential.description)
@@ -20,14 +22,14 @@ object VcVerificationResponse {
 
     object credential
         extends Annotation[String](
-          description = "Encoded Verifiable Credential to verify",
+          description = "Encoded Verifiable Credential that was verified.",
           example =
             "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
         )
 
     object vcVerificationResults
-        extends Annotation[List[VcVerificationResult]](
-          description = "The list executed Verifications",
+        extends Annotation[String](
+          description = "The list of verification results for each verification performed on the credential.",
           example = List(
             VcVerificationResult(VcVerification.SignatureVerification, true),
             VcVerificationResult(VcVerification.IssuerIdentification, true),
@@ -41,7 +43,7 @@ object VcVerificationResponse {
             VcVerificationResult(VcVerification.AlgorithmVerification, true),
             VcVerificationResult(VcVerification.SchemaCheck, true),
             VcVerificationResult(VcVerification.SemanticCheckOfClaims, true),
-          )
+          ).toJson
         )
   }
 

diff --git a/...ain/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResult.scala b/...ain/scala/org/hyperledger/identus/verification/controller/http/VcVerificationResult.scala
@@ -2,10 +2,20 @@ package org.hyperledger.identus.verification.controller.http
 
 import org.hyperledger.identus.pollux.core.service.verification.VcVerificationResult as ServiceVcVerificationResult
 import sttp.tapir.Schema
+import sttp.tapir.Schema.annotations.description
 import zio.json.{DeriveJsonDecoder, DeriveJsonEncoder, JsonDecoder, JsonEncoder}
 
+/** Represents the result of a verification performed on a verifiable credential.
+  *
+  * @param verification
+  *   The type of verification that was performed.
+  * @param success
+  *   Indicates whether the verification was successful.
+  */
 final case class VcVerificationResult(
+    @description("The type of verification that was performed.")
     verification: VcVerification,
+    @description("Indicates whether the verification was successful.")
     success: Boolean
 )
 object VcVerificationResult {