docs(admin): document the 409 response on a2a agent update

[moonming]

What

Adds the missing 409 response to the PUT /admin/v1/a2a_agents/{id} operation in the hand-written admin OpenAPI assembly (crates/aisix-admin/src/openapi.rs), mirroring the wording already used by PUT /admin/v1/mcp_servers/{id} ("Duplicate name", AdminError schema).

Why

The handler can actually return it: update_a2a_agent runs the unique-name check on update too (assert_unique_name(&all, &agent.name, Some(&id)) in crates/aisix-admin/src/a2a_agents_handlers.rs), returning AdminError::Conflict → 409 when the replacement payload reuses another agent's name. The operation's own prose description already says "rejects duplicate name values" — only the response table was missing the code. Every other resource's update operation (models, api_keys, provider_keys, mcp_servers, guardrails, cache_policies, observability_exporters) already documents its 409; a2a_agents was the one gap.

Spec-only change; no runtime behavior touched.

Audit follow-up

An independent audit of the first commit found one MEDIUM: nothing tested 409 documentation, so the omission this PR fixes was unguarded (the suite passed with or without the fix). Addressed in the second commit with openapi_documents_admin_duplicate_name_conflicts, a 409/AdminError parity test over all 8 resources' POST + PUT operations, mirroring the existing 413 body-limit parity test.

Test plan

• cargo run -p aisix-admin --bin dump-openapi > /tmp/admin-api.openapi.json — a2a PUT now lists 200/400/401/404/409/413/415/500; its 409 object is byte-identical to the mcp_server PUT's
• cargo test -p aisix-admin openapi — 20 passed, 0 failed (including the new parity test)

[coderabbitai]

📝 Walkthrough

Walkthrough

The hand-written OpenAPI document adds a 409 response for duplicate name values to PUT /admin/v1/a2a_agents/{id}, referencing the AdminError schema.

Changes

A2A agent OpenAPI documentation

Layer / File(s)	Summary
Document duplicate-name response crates/aisix-admin/src/openapi.rs	The update-agent operation now documents a 409 JSON response for duplicate names using AdminError.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
E2e Test Quality Review	✅ Passed	PASS: The OpenAPI-only change matches handler behavior, mirrors sibling routes, and stays scoped to a missing 409 doc; existing spec tests already cover response-schema consistency.
Security Check	✅ Passed	Doc-only OpenAPI change; the handler already returns 409 Conflict for duplicate names, with no auth/logging/storage code altered.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the documented 409 response added for the a2a agent update endpoint.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/a2a-update-409

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}