Repository navigation
Commit 46b292b
fix(server): improve Swagger /docs example annotations for A2A routes (a2aproject#1092)
## Summary
- Uses `add_a2a_routes_to_fastapi()` in the sample instead of
`app.routes.extend()` — the feature introduced in a2aproject#1024 was not
reflected in the sample
- Adds principled Swagger example annotations to the proto → JSON Schema
generator (`_proto_schema.py`), driven by `google.api.field_behavior`
proto annotations and proto type information rather than hardcoded
field-name lists
### Schema example improvements
| Field type | Before | After |
|---|---|---|
| Enum | no example → Swagger guesses (e.g. `"user"`) causing `-32602` |
first non-`UNSPECIFIED` value (e.g. `ROLE_USER`) |
| String, optional | no example → Swagger generates `"string"` causing
task-lookup failures on `task_id` | `""` (proto3 empty = field unset) |
| String, `REQUIRED` | no example → `"string"` causing validation
failures on `message_id` | `field.name` (non-empty, self-describing) |
| Bool | no example → Swagger picks `true` causing `return_immediately:
true` → `SUBMITTED` | `false` |
| Message, non-`REQUIRED` | expanded inline → optional config sub-fields
fail required-field validation | `oneOf: [$ref, null]` with `example:
null` |
| Message, `REQUIRED` | — | unchanged `$ref` (not nullable) |
| Repeated (array) | no array example → Swagger generates one item per
`oneOf` branch | `[item_example]` (single pre-filled entry) |
| oneOf schema | no example → all branches expanded in arrays | example
using first variant only |
Optionality is derived from `google.api.field_behavior = REQUIRED`
annotations already present on the A2A proto fields — no hardcoded
field-name exceptions.
## Checklist
- [x] Follows [`CONTRIBUTING`
Guide](https://github.com/a2aproject/a2a-python/blob/main/CONTRIBUTING.md)
- [x] PR title follows Conventional Commits
- [x] Tests pass — 95 passing (8 new tests covering the new example
behaviour)
- [x] `ruff format` and `ruff check` clean
Continues a2aproject#1024 🦕
---------
Co-authored-by: Ivan Shymko <ishymko@google.com>1 parent b264a6f commit 46b292b
3 files changed
Lines changed: 175 additions & 51 deletions
File tree
- samples
- src/a2a/server/routes
- tests/server/routes
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
15 | 15 | | |
16 | 16 | | |
17 | 17 | | |
| 18 | + | |
18 | 19 | | |
19 | 20 | | |
20 | 21 | | |
| |||
220 | 221 | | |
221 | 222 | | |
222 | 223 | | |
223 | | - | |
224 | | - | |
225 | | - | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
226 | 230 | | |
227 | 231 | | |
228 | 232 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2 | 2 | | |
3 | 3 | | |
4 | 4 | | |
| 5 | + | |
5 | 6 | | |
6 | 7 | | |
7 | 8 | | |
| |||
33 | 34 | | |
34 | 35 | | |
35 | 36 | | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
36 | 43 | | |
37 | 44 | | |
38 | 45 | | |
| |||
57 | 64 | | |
58 | 65 | | |
59 | 66 | | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
60 | 73 | | |
61 | | - | |
62 | | - | |
63 | | - | |
64 | | - | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
65 | 86 | | |
66 | 87 | | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
67 | 94 | | |
68 | 95 | | |
69 | | - | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
70 | 107 | | |
71 | 108 | | |
72 | 109 | | |
| |||
114 | 151 | | |
115 | 152 | | |
116 | 153 | | |
117 | | - | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
| 168 | + | |
| 169 | + | |
| 170 | + | |
| 171 | + | |
| 172 | + | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
118 | 177 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
59 | 59 | | |
60 | 60 | | |
61 | 61 | | |
62 | | - | |
63 | | - | |
64 | | - | |
65 | | - | |
66 | | - | |
67 | | - | |
68 | | - | |
69 | | - | |
70 | | - | |
71 | | - | |
72 | | - | |
73 | | - | |
74 | | - | |
75 | | - | |
76 | | - | |
77 | | - | |
78 | | - | |
79 | | - | |
80 | | - | |
81 | | - | |
82 | | - | |
83 | | - | |
84 | | - | |
85 | | - | |
86 | | - | |
87 | | - | |
88 | | - | |
89 | | - | |
90 | | - | |
91 | | - | |
92 | | - | |
93 | | - | |
94 | | - | |
95 | | - | |
96 | | - | |
97 | | - | |
98 | | - | |
99 | | - | |
100 | | - | |
101 | | - | |
102 | | - | |
103 | | - | |
104 | 62 | | |
105 | 63 | | |
106 | 64 | | |
| |||
120 | 78 | | |
121 | 79 | | |
122 | 80 | | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
123 | 167 | | |
124 | 168 | | |
125 | 169 | | |
| |||
130 | 174 | | |
131 | 175 | | |
132 | 176 | | |
| 177 | + | |
| 178 | + | |
| 179 | + | |
| 180 | + | |
| 181 | + | |
| 182 | + | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
0 commit comments