🎨 Fix swagger tag names for AnonCreds endpoints (openwallet-foundation#3661)

* 🎨 Use revocation_anoncreds tag title

Signed-off-by: ff137 <ff137@proton.me>

* 🎨 Deduplicate tag titles

Signed-off-by: ff137 <ff137@proton.me>

* 🎨 Deduplicate tag titles

Signed-off-by: ff137 <ff137@proton.me>

* 🎨 Avoid circular import, due to knot between anoncreds/routes and revocation_anoncreds/routes

Signed-off-by: ff137 <ff137@proton.me>

* 🎨 Fix new lines in description summary

Signed-off-by: ff137 <ff137@proton.me>

* 📝 Update openapi spec

Signed-off-by: ff137 <ff137@proton.me>

* 🎨 Reword update description

Signed-off-by: ff137 <ff137@proton.me>

---------

Signed-off-by: ff137 <ff137@proton.me>
Co-authored-by: Stephen Curran <swcurran@gmail.com>

Author: ff137

acapy_agent/anoncreds/routes.py

@@ -48,6 +48,10 @@
 
 LOGGER = logging.getLogger(__name__)
 
+CRED_DEF_TAG_TITLE = "AnonCreds - Credential Definitions"
+SCHEMAS_TAG_TITLE = "AnonCreds - Schemas"
+REVOCATION_TAG_TITLE = "AnonCreds - Revocation"
+
 SPEC_URI = "https://hyperledger.github.io/anoncreds-spec"
 
 endorser_connection_id_description = (
@@ -153,7 +157,10 @@ class SchemaPostRequestSchema(OpenAPISchema):
     options = fields.Nested(SchemaPostOptionSchema())
 
 
-@docs(tags=["anoncreds - schemas"], summary="Create a schema on the connected datastore")
+@docs(
+    tags=[SCHEMAS_TAG_TITLE],
+    summary="Create a schema on the connected datastore",
+)
 @request_schema(SchemaPostRequestSchema())
 @response_schema(SchemaResultSchema(), 200, description="")
 @tenant_authentication
@@ -225,7 +232,10 @@ async def schemas_post(request: web.BaseRequest):
         raise web.HTTPBadRequest(reason=e.roll_up) from e
 
 
-@docs(tags=["anoncreds - schemas"], summary="Retrieve an individual schemas details")
+@docs(
+    tags=[SCHEMAS_TAG_TITLE],
+    summary="Retrieve an individual schemas details",
+)
 @match_info_schema(SchemaIdMatchInfo())
 @response_schema(GetSchemaResultSchema(), 200, description="")
 @tenant_authentication
@@ -255,7 +265,10 @@ async def schema_get(request: web.BaseRequest):
         raise web.HTTPBadRequest(reason=e.roll_up) from e
 
 
-@docs(tags=["anoncreds - schemas"], summary="Retrieve all schema ids")
+@docs(
+    tags=[SCHEMAS_TAG_TITLE],
+    summary="Retrieve all schema ids",
+)
 @querystring_schema(SchemasQueryStringSchema())
 @response_schema(GetSchemasResponseSchema(), 200, description="")
 @tenant_authentication
@@ -397,7 +410,7 @@ class CredDefsQueryStringSchema(OpenAPISchema):
 
 
 @docs(
-    tags=["anoncreds - credential definitions"],
+    tags=[CRED_DEF_TAG_TITLE],
     summary="Create a credential definition on the connected datastore",
 )
 @request_schema(CredDefPostRequestSchema())
@@ -449,7 +462,7 @@ async def cred_def_post(request: web.BaseRequest):
 
 
 @docs(
-    tags=["anoncreds - credential definitions"],
+    tags=[CRED_DEF_TAG_TITLE],
     summary="Retrieve an individual credential definition details",
 )
 @match_info_schema(CredIdMatchInfo())
@@ -497,7 +510,7 @@ class GetCredDefsResponseSchema(OpenAPISchema):
 
 
 @docs(
-    tags=["anoncreds - credential definitions"],
+    tags=[CRED_DEF_TAG_TITLE],
     summary="Retrieve all credential definition ids",
 )
 @querystring_schema(CredDefsQueryStringSchema())
@@ -592,7 +605,7 @@ class RevRegCreateRequestSchemaAnonCreds(OpenAPISchema):
 
 
 @docs(
-    tags=["anoncreds - revocation"],
+    tags=[REVOCATION_TAG_TITLE],
     summary="Create and publish a registration revocation on the connected datastore",
 )
 @request_schema(RevRegCreateRequestSchemaAnonCreds())
@@ -677,7 +690,7 @@ class RevListCreateRequestSchema(OpenAPISchema):
 
 
 @docs(
-    tags=["anoncreds - revocation"],
+    tags=[REVOCATION_TAG_TITLE],
     summary="Create and publish a revocation status list on the connected datastore",
 )
 @request_schema(RevListCreateRequestSchema())
@@ -713,7 +726,7 @@ async def rev_list_post(request: web.BaseRequest):
 
 
 @docs(
-    tags=["anoncreds - revocation"],
+    tags=[REVOCATION_TAG_TITLE],
     summary="Upload local tails file to server",
 )
 @match_info_schema(AnonCredsRevRegIdMatchInfoSchema())
@@ -749,7 +762,7 @@ async def upload_tails_file(request: web.BaseRequest):
 
 
 @docs(
-    tags=["anoncreds - revocation"],
+    tags=[REVOCATION_TAG_TITLE],
     summary="Update the active registry",
 )
 @match_info_schema(AnonCredsRevRegIdMatchInfoSchema())
@@ -820,14 +833,14 @@ def post_process_routes(app: web.Application):
         app._state["swagger_dict"]["tags"] = []
     app._state["swagger_dict"]["tags"].append(
         {
-            "name": "AnonCreds - Schemas",
+            "name": SCHEMAS_TAG_TITLE,
             "description": "AnonCreds schema management",
             "externalDocs": {"description": "Specification", "url": SPEC_URI},
         }
     )
     app._state["swagger_dict"]["tags"].append(
         {
-            "name": "AnonCreds - Credential Definitions",
+            "name": CRED_DEF_TAG_TITLE,
             "description": "AnonCreds credential definition management",
             "externalDocs": {"description": "Specification", "url": SPEC_URI},
         }

acapy_agent/revocation_anoncreds/routes.py

@@ -313,7 +313,7 @@ class PublishRevocationsOptions(OpenAPISchema):
 
     endorser_connection_id = fields.Str(
         metadata={
-            "description": endorser_connection_id_description,  # noqa: F821
+            "description": endorser_connection_id_description,
             "required": False,
             "example": UUIDFour.EXAMPLE,
         }

acapy_agent/wallet/keys/routes.py

@@ -10,6 +10,7 @@
 from ...admin.request_context import AdminRequestContext
 from ...messaging.models.openapi import OpenAPISchema
 from ...wallet.error import WalletDuplicateError, WalletNotFoundError
+from ..routes import WALLET_TAG_TITLE
 from .manager import DEFAULT_ALG, MultikeyManager, MultikeyManagerError
 
 LOGGER = logging.getLogger(__name__)
@@ -124,7 +125,7 @@ class FetchKeyResponseSchema(OpenAPISchema):
     )
 
 
-@docs(tags=["wallet"], summary="Fetch key info.")
+@docs(tags=[WALLET_TAG_TITLE], summary="Fetch key info.")
 @response_schema(FetchKeyResponseSchema, 200, description="")
 @tenant_authentication
 async def fetch_key(request: web.BaseRequest):
@@ -149,7 +150,7 @@ async def fetch_key(request: web.BaseRequest):
         return web.json_response({"message": str(err)}, status=400)
 
 
-@docs(tags=["wallet"], summary="Create a key pair")
+@docs(tags=[WALLET_TAG_TITLE], summary="Create a key pair")
 @request_schema(CreateKeyRequestSchema())
 @response_schema(CreateKeyResponseSchema, 200, description="")
 @tenant_authentication
@@ -184,7 +185,7 @@ async def create_key(request: web.BaseRequest):
         return web.json_response({"message": str(err)}, status=400)
 
 
-@docs(tags=["wallet"], summary="Update a key pair's kid")
+@docs(tags=[WALLET_TAG_TITLE], summary="Update a key pair's kid")
 @request_schema(UpdateKeyRequestSchema())
 @response_schema(UpdateKeyResponseSchema, 200, description="")
 @tenant_authentication

acapy_agent/wallet/routes.py

@@ -88,6 +88,9 @@
 
 LOGGER = logging.getLogger(__name__)
 
+WALLET_TAG_TITLE = "wallet"
+UPGRADE_TAG_TITLE = "AnonCreds - Wallet Upgrade"
+
 
 class WalletModuleResponseSchema(OpenAPISchema):
     """Response schema for Wallet Module."""
@@ -447,7 +450,7 @@ def format_did_info(info: DIDInfo):
         }
 
 
-@docs(tags=["wallet"], summary="List wallet DIDs")
+@docs(tags=[WALLET_TAG_TITLE], summary="List wallet DIDs")
 @querystring_schema(DIDListQueryStringSchema())
 @response_schema(DIDListSchema, 200, description="")
 @tenant_authentication
@@ -553,7 +556,7 @@ async def wallet_did_list(request: web.BaseRequest):
     return web.json_response({"results": results})
 
 
-@docs(tags=["wallet"], summary="Create a local DID")
+@docs(tags=[WALLET_TAG_TITLE], summary="Create a local DID")
 @request_schema(DIDCreateSchema())
 @response_schema(DIDResultSchema, 200, description="")
 @tenant_authentication
@@ -680,7 +683,7 @@ async def wallet_create_did(request: web.BaseRequest):
     return web.json_response({"result": format_did_info(info)})
 
 
-@docs(tags=["wallet"], summary="Fetch the current public DID")
+@docs(tags=[WALLET_TAG_TITLE], summary="Fetch the current public DID")
 @response_schema(DIDResultSchema, 200, description="")
 @tenant_authentication
 async def wallet_get_public_did(request: web.BaseRequest):
@@ -707,7 +710,7 @@ async def wallet_get_public_did(request: web.BaseRequest):
     return web.json_response({"result": format_did_info(info)})
 
 
-@docs(tags=["wallet"], summary="Assign the current public DID")
+@docs(tags=[WALLET_TAG_TITLE], summary="Assign the current public DID")
 @querystring_schema(DIDQueryStringSchema())
 @querystring_schema(CreateAttribTxnForEndorserOptionSchema())
 @querystring_schema(AttribConnIdMatchInfoSchema())
@@ -952,7 +955,10 @@ async def promote_wallet_public_did(
     return info, attrib_def
 
 
-@docs(tags=["wallet"], summary="Update endpoint in wallet and on ledger if posted to it")
+@docs(
+    tags=[WALLET_TAG_TITLE],
+    summary="Update endpoint in wallet and on ledger if posted to it",
+)
 @request_schema(DIDEndpointWithTypeSchema)
 @querystring_schema(CreateAttribTxnForEndorserOptionSchema())
 @querystring_schema(AttribConnIdMatchInfoSchema())
@@ -1083,7 +1089,7 @@ async def wallet_set_did_endpoint(request: web.BaseRequest):
         return web.json_response({"txn": transaction.serialize()})
 
 
-@docs(tags=["wallet"], summary="Create a jws using did keys with a given payload")
+@docs(tags=[WALLET_TAG_TITLE], summary="Create a jws using did keys with a given payload")
 @request_schema(JWSCreateSchema)
 @response_schema(WalletModuleResponseSchema(), description="")
 @tenant_authentication
@@ -1121,7 +1127,10 @@ async def wallet_jwt_sign(request: web.BaseRequest):
     return web.json_response(jws)
 
 
-@docs(tags=["wallet"], summary="Create an sd-jws using did keys with a given payload")
+@docs(
+    tags=[WALLET_TAG_TITLE],
+    summary="Create an sd-jws using did keys with a given payload",
+)
 @request_schema(SDJWSCreateSchema)
 @response_schema(WalletModuleResponseSchema(), description="")
 @tenant_authentication
@@ -1163,7 +1172,7 @@ async def wallet_sd_jwt_sign(request: web.BaseRequest):
     return web.json_response(sd_jws)
 
 
-@docs(tags=["wallet"], summary="Verify a jws using did keys with a given JWS")
+@docs(tags=[WALLET_TAG_TITLE], summary="Verify a jws using did keys with a given JWS")
 @request_schema(JWSVerifySchema())
 @response_schema(JWSVerifyResponseSchema(), 200, description="")
 @tenant_authentication
@@ -1204,7 +1213,7 @@ async def wallet_jwt_verify(request: web.BaseRequest):
 
 
 @docs(
-    tags=["wallet"],
+    tags=[WALLET_TAG_TITLE],
     summary="Verify an sd-jws using did keys with a given SD-JWS with "
     "optional key binding",
 )
@@ -1239,7 +1248,7 @@ async def wallet_sd_jwt_verify(request: web.BaseRequest):
     return web.json_response(result.serialize())
 
 
-@docs(tags=["wallet"], summary="Query DID endpoint in wallet")
+@docs(tags=[WALLET_TAG_TITLE], summary="Query DID endpoint in wallet")
 @querystring_schema(DIDQueryStringSchema())
 @response_schema(DIDEndpointSchema, 200, description="")
 @tenant_authentication
@@ -1273,7 +1282,9 @@ async def wallet_get_did_endpoint(request: web.BaseRequest):
     return web.json_response({"did": did, "endpoint": endpoint})
 
 
-@docs(tags=["wallet"], summary="Rotate keypair for a DID not posted to the ledger")
+@docs(
+    tags=[WALLET_TAG_TITLE], summary="Rotate keypair for a DID not posted to the ledger"
+)
 @querystring_schema(DIDQueryStringSchema())
 @response_schema(WalletModuleResponseSchema(), description="")
 @tenant_authentication
@@ -1329,11 +1340,9 @@ class UpgradeResultSchema(OpenAPISchema):
 
 
 @docs(
-    tags=["anoncreds - wallet upgrade"],
-    summary="""
-        Upgrade the wallet from askar to anoncreds - Be very careful with this! You 
-        cannot go back! See migration guide for more information.
-    """,
+    tags=[UPGRADE_TAG_TITLE],
+    summary="Upgrade the wallet from askar to askar-anoncreds. Be very careful with this!"
+    " You cannot go back! See migration guide for more information.",
 )
 @querystring_schema(UpgradeVerificationSchema())
 @response_schema(UpgradeResultSchema(), description="")
@@ -1484,7 +1493,7 @@ def post_process_routes(app: web.Application):
         app._state["swagger_dict"]["tags"] = []
     app._state["swagger_dict"]["tags"].append(
         {
-            "name": "wallet",
+            "name": WALLET_TAG_TITLE,
             "description": "DID and tag policy management",
             "externalDocs": {
                 "description": "Design",
@@ -1497,7 +1506,7 @@ def post_process_routes(app: web.Application):
     )
     app._state["swagger_dict"]["tags"].append(
         {
-            "name": "AnonCreds - Wallet Upgrade",
+            "name": UPGRADE_TAG_TITLE,
             "description": "AnonCreds wallet upgrade",
             "externalDocs": {
                 "description": "Specification",