Improve api documentation and error handling

aries_cloudagent/anoncreds/base.py

@@ -13,14 +13,13 @@
 from .models.anoncreds_revocation import (
     GetRevListResult,
     GetRevRegDefResult,
-    RevRegDef,
-    RevRegDefResult,
     RevList,
     RevListResult,
+    RevRegDef,
+    RevRegDefResult,
 )
 from .models.anoncreds_schema import AnonCredsSchema, GetSchemaResult, SchemaResult
 
-
 T = TypeVar("T")
 
 

aries_cloudagent/anoncreds/default/legacy_indy/registry.py

@@ -636,15 +636,23 @@ async def register_revocation_list(
             profile, rev_list, rev_reg_def.type, rev_reg_entry
         )
 
+        seq_no = None
+        try:
+            seq_no = rev_entry_res["result"]["txnMetadata"]["seqNo"]
+        except KeyError:
+            LOGGER.warning("Failed to parse sequence number from ledger response")
+
         return RevListResult(
             job_id=None,
             revocation_list_state=RevListState(
                 state=RevListState.STATE_FINISHED,
                 revocation_list=rev_list,
             ),
             registration_metadata={},
-            revocation_list_metadata={
-                "seqNo": rev_entry_res["result"]["txnMetadata"]["seqNo"],
+            revocation_list_metadata={}
+            if seq_no is None
+            else {
+                "seqNo": seq_no,
             },
         )
 

aries_cloudagent/anoncreds/issuer.py

@@ -6,16 +6,14 @@
 from time import time
 from typing import Optional, Sequence
 
-from aries_askar import AskarError
-
 from anoncreds import (
     AnoncredsError,
     Credential,
     CredentialDefinition,
     CredentialOffer,
     Schema,
 )
-
+from aries_askar import AskarError
 
 from ..askar.profile_anon import (
     AskarAnoncredsProfile,

aries_cloudagent/anoncreds/models/anoncreds_cred_def.py

@@ -1,14 +1,19 @@
 """Anoncreds cred def OpenAPI validators."""
 from typing import Optional
-from typing_extensions import Literal
 
 from anoncreds import CredentialDefinition
 from marshmallow import EXCLUDE, fields
 from marshmallow.validate import OneOf
+from typing_extensions import Literal
 
 from ...messaging.models.base import BaseModel, BaseModelSchema
-from ...messaging.valid import NUM_STR_WHOLE_VALIDATE, NUM_STR_WHOLE_EXAMPLE
-
+from ...messaging.valid import (
+    INDY_CRED_DEF_ID_EXAMPLE,
+    INDY_OR_KEY_DID_EXAMPLE,
+    INDY_SCHEMA_ID_EXAMPLE,
+    NUM_STR_WHOLE_EXAMPLE,
+    NUM_STR_WHOLE_VALIDATE,
+)
 
 NUM_STR_WHOLE = {"validate": NUM_STR_WHOLE_VALIDATE, "example": NUM_STR_WHOLE_EXAMPLE}
 
@@ -239,12 +244,18 @@ class Meta:
     issuer_id = fields.Str(
         description="Issuer Identifier of the credential definition or schema",
         data_key="issuerId",
+        example=INDY_OR_KEY_DID_EXAMPLE,
+    )
+    schema_id = fields.Str(
+        data_key="schemaId",
+        description="Schema identifier",
+        example=INDY_SCHEMA_ID_EXAMPLE,
     )
-    schema_id = fields.Str(data_key="schemaId", description="Schema identifier")
     type = fields.Str(validate=OneOf(["CL"]))
     tag = fields.Str(
         description="""The tag value passed in by the Issuer to
-         an AnonCred's Credential Definition create and store implementation."""
+         an AnonCred's Credential Definition create and store implementation.""",
+        example="default",
     )
     value = fields.Nested(CredDefValueSchema())
 
@@ -303,7 +314,9 @@ class Meta:
         )
     )
     credential_definition_id = fields.Str(
-        description="credential definition id", allow_none=True
+        description="credential definition id",
+        allow_none=True,
+        example=INDY_CRED_DEF_ID_EXAMPLE,
     )
     credential_definition = fields.Nested(
         CredDefSchema(), description="credential definition"
@@ -403,7 +416,10 @@ class Meta:
         model_class = GetCredDefResult
         unknown = EXCLUDE
 
-    credential_definition_id = fields.Str(description="credential definition id")
+    credential_definition_id = fields.Str(
+        description="credential definition id",
+        example=INDY_CRED_DEF_ID_EXAMPLE,
+    )
     credential_definition = fields.Nested(
         CredDefSchema(), description="credential definition"
     )

aries_cloudagent/anoncreds/models/anoncreds_revocation.py

@@ -1,10 +1,18 @@
 """Anoncreds cred def OpenAPI validators."""
 from typing import Any, Dict, List, Optional
-from typing_extensions import Literal
 
 from anoncreds import RevocationRegistryDefinition, RevocationStatusList
 from marshmallow import EXCLUDE, fields
 from marshmallow.validate import OneOf
+from typing_extensions import Literal
+
+from aries_cloudagent.messaging.valid import (
+    INDY_CRED_DEF_ID_EXAMPLE,
+    INDY_ISO8601_DATETIME_EXAMPLE,
+    INDY_OR_KEY_DID_EXAMPLE,
+    INDY_RAW_PUBLIC_KEY_EXAMPLE,
+    INDY_REV_REG_ID_EXAMPLE,
+)
 
 from ...messaging.models.base import BaseModel, BaseModelSchema
 
@@ -52,10 +60,17 @@ class Meta:
         model_class = RevRegDefValue
         unknown = EXCLUDE
 
-    public_keys = fields.Dict(data_key="publicKeys")
-    max_cred_num = fields.Int(data_key="maxCredNum")
-    tails_location = fields.Str(data_key="tailsLocation")
-    tails_hash = fields.Str(data_key="tailsHash")
+    public_keys = fields.Dict(
+        data_key="publicKeys", example=INDY_RAW_PUBLIC_KEY_EXAMPLE
+    )
+    max_cred_num = fields.Int(data_key="maxCredNum", example=666)
+    tails_location = fields.Str(
+        data_key="tailsLocation",
+        example="https://tails-server.com/hash/7Qen9RDyemMuV7xGQvp7NjwMSpyHieJyBakycxN7dX7P",
+    )
+    tails_hash = fields.Str(
+        data_key="tailsHash", example="7Qen9RDyemMuV7xGQvp7NjwMSpyHieJyBakycxN7dX7P"
+    )
 
 
 class RevRegDef(BaseModel):
@@ -116,13 +131,17 @@ class Meta:
     issuer_id = fields.Str(
         description="Issuer Identifier of the credential definition or schema",
         data_key="issuerId",
+        example=INDY_OR_KEY_DID_EXAMPLE,
     )
     type = fields.Str(data_key="revocDefType")
     cred_def_id = fields.Str(
         description="Credential definition identifier",
         data_key="credDefId",
+        example=INDY_CRED_DEF_ID_EXAMPLE,
+    )
+    tag = fields.Str(
+        description="tag for the revocation registry definition", example="default"
     )
-    tag = fields.Str(description="tag for the revocation registry definition")
     value = fields.Nested(RevRegDefValueSchema())
 
 
@@ -184,7 +203,8 @@ class Meta:
         )
     )
     revocation_registry_definition_id = fields.Str(
-        description="revocation registry definition id"
+        description="revocation registry definition id",
+        example=INDY_REV_REG_ID_EXAMPLE,
     )
     revocation_registry_definition = fields.Nested(
         RevRegDefSchema(), description="revocation registry definition"
@@ -362,20 +382,28 @@ class Meta:
     issuer_id = fields.Str(
         description="Issuer Identifier of the credential definition or schema",
         data_key="issuerId",
+        example=INDY_OR_KEY_DID_EXAMPLE,
     )
     rev_reg_def_id = fields.Str(
-        description="",
+        description="The ID of the revocation registry definition",
         data_key="revRegDefId",
+        example=INDY_REV_REG_ID_EXAMPLE,
     )
     revocation_list = fields.List(
         fields.Int(),
         description="Bit list representing revoked credentials",
         data_key="revocationList",
+        example=[0, 1, 1, 0],
+    )
+    current_accumulator = fields.Str(
+        description="The current accumalator value",
+        example="21 118...1FB",
+        data_key="currentAccumulator",
     )
-    current_accumulator = fields.Str(data_key="currentAccumulator")
     timestamp = fields.Int(
         description="Timestamp at which revocation list is applicable",
         required=False,
+        example=INDY_ISO8601_DATETIME_EXAMPLE,
     )
 
 

aries_cloudagent/anoncreds/models/anoncreds_schema.py

@@ -2,10 +2,14 @@
 
 from typing import Any, Dict, List, Optional
 
+from anoncreds import Schema
 from marshmallow import EXCLUDE, fields
 from marshmallow.validate import OneOf
 
-from anoncreds import Schema
+from aries_cloudagent.messaging.valid import (
+    INDY_OR_KEY_DID_EXAMPLE,
+    INDY_SCHEMA_ID_EXAMPLE,
+)
 
 from ...messaging.models.base import BaseModel, BaseModelSchema
 
@@ -60,6 +64,7 @@ class Meta:
     issuer_id = fields.Str(
         description="Issuer Identifier of the credential definition or schema",
         data_key="issuerId",
+        example=INDY_OR_KEY_DID_EXAMPLE,
     )
     attr_names = fields.List(
         fields.Str(
@@ -69,10 +74,8 @@ class Meta:
         description="Schema attribute names",
         data_key="attrNames",
     )
-    name = fields.Str(
-        description="Schema name",
-    )
-    version = fields.Str(description="Schema version")
+    name = fields.Str(description="Schema name", example="Example schema")
+    version = fields.Str(description="Schema version", example="1.0")
 
 
 class GetSchemaResult(BaseModel):
@@ -127,7 +130,9 @@ class Meta:
         unknown = EXCLUDE
 
     schema_value = fields.Nested(AnonCredsSchemaSchema(), data_key="schema")
-    schema_id = fields.Str(data_key="schemaId", description="Schema identifier")
+    schema_id = fields.Str(
+        description="Schema identifier", example=INDY_SCHEMA_ID_EXAMPLE
+    )
     resolution_metadata = fields.Dict()
     schema_metadata = fields.Dict()
 
@@ -179,7 +184,10 @@ class Meta:
             ]
         )
     )
-    schema_id = fields.Str(description="Schema identifier")
+    schema_id = fields.Str(
+        description="Schema identifier",
+        example=INDY_SCHEMA_ID_EXAMPLE,
+    )
     schema_value = fields.Nested(AnonCredsSchemaSchema(), data_key="schema")
 
 

aries_cloudagent/anoncreds/registry.py

@@ -53,6 +53,10 @@ async def _resolver_for_identifier(self, identifier: str) -> BaseAnonCredsResolv
             for resolver in self.resolvers
             if await resolver.supports(identifier)
         ]
+        if len(resolvers) == 0:
+            raise AnonCredsResolutionError(
+                f"No resolver available for identifier {identifier}"
+            )
         if len(resolvers) > 1:
             raise AnonCredsResolutionError(
                 f"More than one resolver found for identifier {identifier}"
@@ -67,6 +71,11 @@ async def _registrar_for_identifier(
             for registrar in self.registrars
             if await registrar.supports(identifier)
         ]
+        if len(registrars) == 0:
+            raise AnonCredsRegistrationError(
+                f"No registrar available for identifier {identifier}"
+            )
+
         if len(registrars) > 1:
             raise AnonCredsRegistrationError(
                 f"More than one registrar found for identifier {identifier}"