fix(server): improve Swagger /docs example annotations for A2A routes

samples/hello_world_agent.py

@@ -15,6 +15,7 @@
 from a2a.server.events.event_queue import EventQueue
 from a2a.server.request_handlers import DefaultRequestHandler, GrpcHandler
 from a2a.server.routes import (
+    add_a2a_routes_to_fastapi,
     create_agent_card_routes,
     create_jsonrpc_routes,
     create_rest_routes,
@@ -220,9 +221,12 @@ async def serve(
         agent_card=agent_card,
     )
     app = FastAPI()
-    app.routes.extend(jsonrpc_routes)
-    app.routes.extend(agent_card_routes)
-    app.routes.extend(rest_routes)
+    add_a2a_routes_to_fastapi(
+        app,
+        agent_card_routes=agent_card_routes,
+        jsonrpc_routes=jsonrpc_routes,
+        rest_routes=rest_routes,
+    )
 
     grpc_server = grpc.aio.server()
     grpc_server.add_insecure_port(f'{host}:{grpc_port}')

src/a2a/server/routes/_proto_schema.py

@@ -2,6 +2,7 @@
 
 from typing import Any
 
+from google.api import field_behavior_pb2 as _fb
 from google.protobuf.descriptor import Descriptor, FieldDescriptor
 from google.protobuf.message import Message
 
@@ -33,6 +34,15 @@
     FieldDescriptor.TYPE_SINT64: {'type': 'string'},
 }
 
+
+def _is_required(field: FieldDescriptor) -> bool:
+    """Returns True if the field carries google.api.field_behavior = REQUIRED."""
+    try:
+        return _fb.REQUIRED in field.GetOptions().Extensions[_fb.field_behavior]  # type: ignore[index]  # ty: ignore[invalid-argument-type]
+    except KeyError:
+        return False
+
+
 _WELL_KNOWN_SCHEMAS: dict[str, dict[str, Any]] = {
     'google.protobuf.Timestamp': {'type': 'string', 'format': 'date-time'},
     'google.protobuf.Duration': {'type': 'string'},
@@ -57,16 +67,46 @@ def field_schema(
 
     if field.type == FieldDescriptor.TYPE_MESSAGE:
         item = message_schema(field.message_type, components)
+        # Well-known types return an inline schema (no $ref); don't wrap them as
+        # nullable — they're already inlined as their JSON-Schema equivalent.
+        # Repeated fields must not return early here — they fall through to the
+        # array-wrapping block below.
+        if not field.is_repeated and not _is_required(field) and '$ref' in item:
+            return {'oneOf': [item, {'type': 'null'}], 'example': None}
     elif field.type == FieldDescriptor.TYPE_ENUM:
-        item = {
-            'type': 'string',
-            'enum': [v.name for v in field.enum_type.values],
-        }
+        values = [v.name for v in field.enum_type.values]
+        example = next(
+            (
+                v
+                for v in values
+                if 'UNSPECIFIED' not in v and 'UNKNOWN' not in v
+            ),
+            values[0] if values else None,
+        )
+        item: dict[str, Any] = {'type': 'string', 'enum': values}
+        if example:
+            item['example'] = example
     else:
         item = dict(_PROTO_SCALAR_SCHEMAS.get(field.type, {'type': 'string'}))
+        if field.type == FieldDescriptor.TYPE_STRING:
+            # REQUIRED fields must be non-empty; use the field name as a
+            # recognisable placeholder. All other strings default to "".
+            item['example'] = field.name if _is_required(field) else ''
+        elif field.type == FieldDescriptor.TYPE_BOOL:
+            item['example'] = False
 
     if field.is_repeated:
-        return {'type': 'array', 'items': item}
+        array_schema: dict[str, Any] = {'type': 'array', 'items': item}
+        # Propagate the item example to the array so Swagger pre-fills one entry
+        # instead of generating one entry per oneOf branch.
+        item_example = (
+            components.get(item['$ref'].split('/')[-1], {}).get('example')
+            if '$ref' in item
+            else item.get('example')
+        )
+        if item_example is not None:
+            array_schema['example'] = [item_example]
+        return array_schema
     return item
 
 
@@ -114,5 +154,27 @@ def message_schema(
     if base_properties:
         parts.append({'type': 'object', 'properties': base_properties})
     parts.extend(oneof_constraints)
-    components[name] = parts[0] if len(parts) == 1 else {'allOf': parts}
+    schema: dict[str, Any] = parts[0] if len(parts) == 1 else {'allOf': parts}
+    # Provide a single concrete example using the first oneof variant so Swagger
+    # doesn't expand every branch into separate array items.
+    first_oneof_field = real_oneofs[0].fields[0]
+    first_field_schema = field_schema(first_oneof_field, components)
+    if 'example' in first_field_schema:
+        first_example: Any = first_field_schema['example']
+    elif '$ref' in first_field_schema:
+        ref_name = first_field_schema['$ref'].split('/')[-1]
+        first_example = components.get(ref_name, {}).get('example')
+    else:
+        _type_defaults: dict[str, Any] = {
+            'integer': 0,
+            'number': 0.0,
+            'boolean': False,
+            'array': [],
+            'object': {},
+        }
+        first_example = _type_defaults.get(
+            first_field_schema.get('type', 'string'), ''
+        )
+    schema['example'] = {first_oneof_field.name: first_example}
+    components[name] = schema
     return ref

tests/server/routes/test_proto_schema.py

@@ -120,6 +120,185 @@ def test_field_schema_enum():
     assert 'ROLE_AGENT' in schema['enum']
 
 
+def test_field_schema_enum_example_skips_unspecified():
+    role_field = Message.DESCRIPTOR.fields_by_name['role']
+    schema = field_schema(role_field, {})
+    assert schema['example'] == 'ROLE_USER'
+
+
+def test_field_schema_string_example_is_empty():
+    context_id_field = Message.DESCRIPTOR.fields_by_name['context_id']
+    schema = field_schema(context_id_field, {})
+    assert schema['example'] == ''
+
+
+def test_field_schema_string_required_uses_field_name():
+    # REQUIRED string fields must be non-empty; the field name is the placeholder.
+    message_id_field = Message.DESCRIPTOR.fields_by_name['message_id']
+    schema = field_schema(message_id_field, {})
+    assert schema['example'] == 'message_id'
+
+
+def test_field_schema_bool_example_is_false():
+    from a2a.types.a2a_pb2 import SendMessageConfiguration
+
+    field = SendMessageConfiguration.DESCRIPTOR.fields_by_name[
+        'return_immediately'
+    ]
+    schema = field_schema(field, {})
+    assert schema['example'] is False
+
+
+def test_field_schema_optional_message_is_nullable():
+    # Non-REQUIRED message fields default to null so Swagger doesn't pre-fill them
+    # with empty sub-fields that trigger server-side required-field validation.
+    from a2a.types.a2a_pb2 import SendMessageConfiguration
+
+    field = SendMessageConfiguration.DESCRIPTOR.fields_by_name[
+        'task_push_notification_config'
+    ]
+    schema = field_schema(field, {})
+    assert schema['example'] is None
+    assert any(v == {'type': 'null'} for v in schema['oneOf'])
+
+
+def test_field_schema_required_message_is_not_nullable():
+    from a2a.types.a2a_pb2 import SendMessageRequest
+
+    field = SendMessageRequest.DESCRIPTOR.fields_by_name['message']
+    schema = field_schema(field, {})
+    assert '$ref' in schema
+    assert 'oneOf' not in schema
+
+
+def test_field_schema_repeated_optional_message_is_array_not_nullable():
+    # Repeated non-REQUIRED message fields must be wrapped as an array, not
+    # returned early as a nullable oneOf — the is_repeated check must come after.
+    from unittest.mock import MagicMock
+
+    from google.protobuf.descriptor import FieldDescriptor as FD
+
+    msg_type = MagicMock()
+    msg_type.GetOptions.return_value.map_entry = False
+    msg_type.name = 'Dummy'
+    msg_type.full_name = 'test.Dummy'
+    msg_type.oneofs = []
+    msg_type.fields = []
+
+    field = MagicMock()
+    field.message_type = msg_type
+    field.type = FD.TYPE_MESSAGE
+    field.is_repeated = True
+    field.GetOptions.return_value.Extensions = {}  # not REQUIRED
+
+    components = {'Dummy': {'type': 'object', 'properties': {}}}
+    schema = field_schema(field, components)
+    assert schema['type'] == 'array'
+    assert 'oneOf' not in schema
+
+
+def test_message_schema_oneof_example_uses_first_variant_only():
+    components = {}
+    message_schema(Part.DESCRIPTOR, components)
+    example = components['Part']['example']
+    assert example == {'text': ''}
+    # base properties (metadata, filename, media_type) must not appear in the
+    # example — they are objects/strings that would be wrong if sent as "".
+    assert 'metadata' not in example
+    assert 'filename' not in example
+
+
+def test_field_schema_repeated_ref_example_propagated():
+    components = {}
+    msg_descriptor = SendMessageRequest.DESCRIPTOR.fields_by_name[
+        'message'
+    ].message_type
+    parts_field = msg_descriptor.fields_by_name['parts']
+    schema = field_schema(parts_field, components)
+    assert schema['type'] == 'array'
+    assert schema['example'] == [{'text': ''}]
+
+
+def _mock_scalar_field(name, ftype):
+    from unittest.mock import MagicMock
+
+    f = MagicMock()
+    f.name = name
+    f.message_type = None
+    f.type = ftype
+    f.is_repeated = False
+    f.GetOptions.return_value.Extensions = {}  # not REQUIRED
+    return f
+
+
+def _mock_oneof_descriptor(full_name, name, fields):
+    from unittest.mock import MagicMock
+
+    oneof = MagicMock()
+    oneof.fields = fields
+    descriptor = MagicMock()
+    descriptor.full_name = full_name
+    descriptor.name = name
+    descriptor.oneofs = [oneof]
+    descriptor.fields = fields
+    return descriptor
+
+
+def test_message_schema_oneof_example_non_string_first_variant_uses_type_default():
+    # When the first oneof variant is a non-string scalar (no example emitted),
+    # the example falls back to the JSON-Schema type default (integer -> 0).
+    from google.protobuf.descriptor import FieldDescriptor as FD
+
+    descriptor = _mock_oneof_descriptor(
+        'test.IntFirstOneof',
+        'IntFirstOneof',
+        [
+            _mock_scalar_field('count', FD.TYPE_INT32),
+            _mock_scalar_field('label', FD.TYPE_STRING),
+        ],
+    )
+    components = {}
+    message_schema(descriptor, components)
+    assert components['IntFirstOneof']['example'] == {'count': 0}
+
+
+def test_message_schema_oneof_example_message_first_variant_resolves_ref():
+    # When the first oneof variant is a (REQUIRED) message type, the example is
+    # resolved from the referenced component schema rather than assumed a string.
+    from unittest.mock import MagicMock
+
+    from google.api import field_behavior_pb2 as fb
+    from google.protobuf.descriptor import FieldDescriptor as FD
+
+    inner = MagicMock()
+    inner.GetOptions.return_value.map_entry = False
+    inner.name = 'Inner'
+    inner.full_name = 'test.Inner'
+    inner.oneofs = []
+    inner.fields = []
+
+    msg_field = MagicMock()
+    msg_field.name = 'payload'
+    msg_field.message_type = inner
+    msg_field.type = FD.TYPE_MESSAGE
+    msg_field.is_repeated = False
+    # REQUIRED so field_schema returns a bare $ref (not a nullable oneOf).
+    msg_field.GetOptions.return_value.Extensions = {
+        fb.field_behavior: [fb.REQUIRED]
+    }
+
+    descriptor = _mock_oneof_descriptor(
+        'test.MsgFirstOneof',
+        'MsgFirstOneof',
+        [msg_field, _mock_scalar_field('note', FD.TYPE_STRING)],
+    )
+    components = {}
+    message_schema(descriptor, components)
+    # Inner has no example of its own, so $ref resolution yields None.
+    assert components['MsgFirstOneof']['example'] == {'payload': None}
+    assert 'Inner' in components
+
+
 def test_field_schema_map_entry():
     metadata_field = SendMessageRequest.DESCRIPTOR.fields_by_name['metadata']
     schema = field_schema(metadata_field, {})