chore: add documentation for DIDMethods

* Augment existing swagger documentation for the `POST
  /wallet/did/create` route
* Add `DIDMethods.md` documentation to introduce the concept of the
  `DIDMethods` registry and its use to register new methods.

Signed-off-by: Clément Humbert <[email protected]>

DIDMethods.md

@@ -0,0 +1,45 @@
+# DID methods in ACA-Py
+Decentralized Identifiers, or DIDs, are URIs that point to documents that describe cryptographic primitives and protocols used in decentralized identity management.
+DIDs include methods that describe where and how documents can be retrieved.
+DID methods support specific types of keys and may or may not require the holder to specify the DID itself.
+
+ACA-Py provides a `DIDMethods` registry holding all the DID methods supported for storage in a wallet
+
+> :warning: Askar and InMemory are the only wallets supporting this registry.
+
+## Registering a DID method
+By default, ACA-Py supports `did:key` and `did:sov`.
+Plugins can register DID additional methods to make them available to holders. 
+Here's a snippet adding support for `did:web` to the registry from a plugin `setup` method.
+
+```python=
+WEB = DIDMethod(
+    name="web",
+    key_types=[ED25519, BLS12381G2],
+    rotation=True,
+    holder_defined_did=HolderDefinedDid.REQUIRED  # did:web is not derived from key material but from a user-provided respository name
+)
+
+async def setup(context: InjectionContext):
+    methods = context.inject(DIDMethods)
+    methods.register(WEB)
+```
+
+## Creating a DID
+
+`POST /wallet/did/create` can be provided with parameters for any registered DID method. Here's a follow-up to the
+`did:web` method example:
+
+```json=
+{
+    "method": "web",
+    "options": {
+        "did": "did:web:doma.in",
+        "key_type": "ed25519"
+    }
+}
+```
+
+## Resolving DIDs
+
+For specifics on how DIDs are resolved in ACA-Py, see: [DID Resolution](DIDResolution.md).

aries_cloudagent/wallet/routes.py

@@ -161,10 +161,17 @@ class DIDCreateOptionsSchema(OpenAPISchema):
     key_type = fields.Str(
         required=True,
         example=ED25519.key_type,
+        description="Key type to use for the DID keypair. "
+        + "Validated with the chosen DID method's supported key types.",
         validate=validate.OneOf([ED25519.key_type, BLS12381G2.key_type]),
     )
 
-    did = fields.Str(required=False, **GENERIC_DID)
+    did = fields.Str(
+        required=False,
+        description="Specify final value of the did (including did:<method>: prefix)"
+        + "if the method supports or requires so.",
+        **GENERIC_DID,
+    )
 
 
 class DIDCreateSchema(OpenAPISchema):
@@ -174,12 +181,14 @@ class DIDCreateSchema(OpenAPISchema):
         required=False,
         default=SOV.method_name,
         example=SOV.method_name,
+        description="Method for the requested DID."
+        + "Supported methods are 'key', 'sov', and any other registered method.",
     )
 
     options = fields.Nested(
         DIDCreateOptionsSchema,
         required=False,
-        description="To define a key type for a did:key",
+        description="To define a key type and/or a did depending on chosen DID method.",
     )
 
     seed = fields.Str(