Admin api richer hints

aries_cloudagent/admin/server.py

@@ -30,7 +30,10 @@
 class AdminModulesSchema(Schema):
     """Schema for the modules endpoint."""
 
-    result = fields.List(fields.Str())
+    result = fields.List(
+        fields.Str(description="admin module"),
+        description="List of admin modules",
+    )
 
 
 class AdminStatusSchema(Schema):

aries_cloudagent/messaging/actionmenu/messages/menu.py

@@ -55,7 +55,23 @@ class Meta:
 
         model_class = Menu
 
-    title = fields.Str(required=False)
-    description = fields.Str(required=False)
-    errormsg = fields.Str(required=False)
-    options = fields.List(fields.Nested(MenuOptionSchema), required=True)
+    title = fields.Str(
+        required=False,
+        description="Menu title",
+        example="My Menu",
+    )
+    description = fields.Str(
+        required=False,
+        description="Introductory text for the menu",
+        example="This menu presents options",
+    )
+    errormsg = fields.Str(
+        required=False,
+        description="An optional error message to display in menu header",
+        example="Error: item not found",
+    )
+    options = fields.List(
+        fields.Nested(MenuOptionSchema),
+        required=True,
+        description="List of menu options",
+    )

aries_cloudagent/messaging/actionmenu/messages/perform.py

@@ -43,5 +43,13 @@ class Meta:
 
         model_class = Perform
 
-    name = fields.Str(required=True)
-    params = fields.Dict(fields.Str(), fields.Str(), required=False)
+    name = fields.Str(
+        required=True,
+        description="Menu option name",
+        example="Query",
+    )
+    params = fields.Dict(
+        required=False,
+        keys=fields.Str(example="parameter"),  # marshmallow/apispec v3.0 ignores
+        values=fields.Str(example="value"),
+    )

aries_cloudagent/messaging/actionmenu/models/menu_form.py

@@ -48,7 +48,25 @@ class Meta:
 
         model_class = MenuForm
 
-    title = fields.Str(required=False)
-    description = fields.Str(required=False)
-    params = fields.List(fields.Nested(MenuFormParamSchema()), required=False)
-    submit_label = fields.Str(data_key="submit-label", required=False)
+    title = fields.Str(
+        required=False,
+        description="Menu form title",
+        example="Preferences",
+    )
+    description = fields.Str(
+        required=False,
+        description="Additional descriptive text for menu form",
+        example="Window preference settings",
+    )
+    params = fields.List(
+        fields.Nested(MenuFormParamSchema()),
+        required=False,
+        description="List of form parameters",
+        example="[alpha, x_offset, y_offset, height, width, bgcolor, fgcolor]",
+    )
+    submit_label = fields.Str(
+        required=False,
+        data_key="submit-label",
+        description="Alternative label for form submit button",
+        example="Send",
+    )

aries_cloudagent/messaging/actionmenu/models/menu_form_param.py

@@ -31,6 +31,9 @@ def __init__(
             title: The parameter title
             default: A default value for the parameter
             description: Additional descriptive text for the menu form parameter
+            input_type: Input type
+            required: Whether the parameter is required
+
         """
         self.name = name
         self.title = title
@@ -48,9 +51,34 @@ class Meta:
 
         model_class = MenuFormParam
 
-    name = fields.Str(required=True)
-    title = fields.Str(required=True)
-    default = fields.Str(required=False)
-    description = fields.Str(required=False)
-    input_type = fields.Str(required=False, data_key="type")
-    required = fields.Bool(required=False)
+    name = fields.Str(
+        required=True,
+        description="Menu parameter name",
+        example="delay",
+    )
+    title = fields.Str(
+        required=True,
+        description="Menu parameter title",
+        example="Delay in seconds"
+    )
+    default = fields.Str(
+        required=False,
+        description="Default parameter value",
+        example="0",
+    )
+    description = fields.Str(
+        required=False,
+        description="Additional descriptive text for menu form parameter",
+        example="Delay in seconds before starting",
+    )
+    input_type = fields.Str(
+        required=False,
+        description="Menu form parameter input type",
+        example="int",
+        data_key="type",
+    )
+    required = fields.Bool(
+        required=False,
+        description="Whether parameter is required",
+        example="False",
+    )

aries_cloudagent/messaging/actionmenu/models/menu_option.py

@@ -49,8 +49,27 @@ class Meta:
 
         model_class = MenuOption
 
-    name = fields.Str(required=True)
-    title = fields.Str(required=True)
-    description = fields.Str(required=False)
-    disabled = fields.Bool(required=False)
-    form = fields.Nested(MenuFormSchema(), required=False)
+    name = fields.Str(
+        required=True,
+        description="Menu option name (unique identifier)",
+        example="window_prefs",
+    )
+    title = fields.Str(
+        required=True,
+        description="Menu option title",
+        example="Window Preferences",
+    )
+    description = fields.Str(
+        required=False,
+        description="Additional descriptive text for menu option",
+        example="Window display preferences",
+    )
+    disabled = fields.Bool(
+        required=False,
+        description="Whether to show option as disabled",
+        example="False",
+    )
+    form = fields.Nested(
+        MenuFormSchema(),
+        required=False,
+    )

aries_cloudagent/messaging/actionmenu/routes.py

@@ -7,12 +7,13 @@
 
 from marshmallow import fields, Schema
 
+from ...storage.error import StorageNotFoundError
 from ..connections.models.connection_record import ConnectionRecord
+from ..valid import UUIDFour
 from .messages.menu import Menu
 from .messages.menu_request import MenuRequest
 from .messages.perform import Perform
 from .models.menu_option import MenuOptionSchema
-from ...storage.error import StorageNotFoundError
 from .util import retrieve_connection_menu, save_connection_menu
 
 LOGGER = logging.getLogger(__name__)
@@ -21,23 +22,48 @@
 class PerformRequestSchema(Schema):
     """Request schema for performing a menu action."""
 
-    name = fields.Str()
-    params = fields.Dict(required=False)
+    name = fields.Str(description="Menu option name", example="Query")
+    params = fields.Dict(
+        description=("Input parameter values"),
+        required=False,
+        keys=fields.Str(example="parameter"),  # marshmallow/apispec v3.0 ignores
+        values=fields.Str(example=UUIDFour.EXAMPLE),
+    )
 
 
 class MenuJsonSchema(Schema):
     """Matches MenuSchema but without the inherited AgentMessage properties."""
 
-    title = fields.Str(required=False)
-    description = fields.Str(required=False)
-    errormsg = fields.Str(required=False)
-    options = fields.List(fields.Nested(MenuOptionSchema), required=True)
+    title = fields.Str(
+        required=False,
+        description="Menu title",
+        example="My Menu",
+    )
+    description = fields.Str(
+        required=False,
+        description="Introductory text for the menu",
+        example="User preferences for window settings",
+    )
+    errormsg = fields.Str(
+        required=False,
+        description="Optional error message to display in menu header",
+        example="Error: item not present",
+    )
+    options = fields.List(
+        fields.Nested(MenuOptionSchema),
+        required=True,
+        description="List of menu options",
+    )
 
 
 class SendMenuSchema(Schema):
     """Request schema for sending a menu to a connection."""
 
-    menu = fields.Nested(MenuJsonSchema(), required=True)
+    menu = fields.Nested(
+        MenuJsonSchema(),
+        required=True,
+        description="Menu to send to connection",
+    )
 
 
 @docs(

aries_cloudagent/messaging/agent_message.py

@@ -26,6 +26,7 @@
     resolve_class,
     resolve_meta_property,
 )
+from .valid import UUIDFour
 
 
 class AgentMessageError(BaseModelError):
@@ -301,8 +302,19 @@ class Meta:
         signed_fields = None
 
     # Avoid clobbering keywords
-    _type = fields.Str(data_key="@type", dump_only=True, required=False)
-    _id = fields.Str(data_key="@id", required=False)
+    _type = fields.Str(
+        data_key="@type",
+        dump_only=True,
+        required=False,
+        description="Message type",
+        example="did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/my-family/1.0/my-message-type",
+    )
+    _id = fields.Str(
+        data_key="@id",
+        required=False,
+        description="Message identifier",
+        example=UUIDFour.EXAMPLE,
+    )
 
     def __init__(self, *args, **kwargs):
         """

aries_cloudagent/messaging/basicmessage/messages/basicmessage.py

@@ -7,6 +7,7 @@
 
 from ...agent_message import AgentMessage, AgentMessageSchema
 from ...util import datetime_now, datetime_to_str
+from ...valid import INDY_ISO8601_DATETIME
 
 from ..message_types import BASIC_MESSAGE
 
@@ -40,6 +41,8 @@ def __init__(
         Args:
             sent_time: Time message was sent
             content: message content
+            localization: localization
+
         """
         super(BasicMessage, self).__init__(**kwargs)
         if not sent_time:
@@ -57,6 +60,19 @@ class Meta:
 
         model_class = BasicMessage
 
-    localization = fields.Str(data_key="l10n", required=False)
-    sent_time = fields.Str(required=False)
-    content = fields.Str(required=True)
+    localization = fields.Str(
+        required=False,
+        description="Localization",
+        example="en-CA",
+        data_key="l10n",
+    )
+    sent_time = fields.Str(
+        required=False,
+        description="Time message was sent, ISO8601 with space date/time separator",
+        **INDY_ISO8601_DATETIME
+    )
+    content = fields.Str(
+        required=True,
+        description="Message content",
+        example="Hello",
+    )

aries_cloudagent/messaging/basicmessage/routes.py

@@ -16,7 +16,10 @@
 class SendMessageSchema(Schema):
     """Request schema for sending a message."""
 
-    content = fields.Str()
+    content = fields.Str(
+        description="Message content",
+        example="Hello"
+    )
 
 
 @docs(tags=["basicmessage"], summary="Send a basic message to a connection")

aries_cloudagent/messaging/connections/manager.py

@@ -683,7 +683,7 @@ async def create_did_document(
 
         Args:
             my_info: The DID I am using in this connection
-            inbound_connection_id: The DID of the inbound routing connection to use
+            inbound_connection_id: The inbound routing connection id to use
             my_endpoint: A custom endpoint for the DID Document
 
         Returns: