fix(server): generate complete OpenAPI schema using compiled protobuf specifications

[guglielmo-san]

Description

This PR addresses OpenAPI serialization in the REST and JSON-RPC FastAPI bindings, ensuring that the interactive Swagger documentation parses and displays A2A v1.0 Protobuf inputs/outputs for the REST server, removing it from the JSON-RPC. Indeed the a2a.json generate file from the a2a.proto is compatible with the REST transport, but not with the JSON-RPC.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refactors the OpenAPI schema generation logic within the A2A server applications. The core change involves centralizing the Protobuf-based OpenAPI schema loading into the REST server, where it is compatible and provides accurate documentation for A2A v1.0 Protobuf types. Concurrently, the JSON-RPC server's application setup has been streamlined by removing this incompatible custom OpenAPI handling, ensuring each server correctly manages its API documentation.

Highlights

• OpenAPI Schema Generation Relocation: The custom A2AFastAPI class, responsible for loading a2a.json to generate OpenAPI schemas from compiled Protobuf specifications, has been moved from the JSON-RPC application to the REST application.
• REST Server OpenAPI Enhancement: The REST server now utilizes the A2AFastAPI class to correctly parse and display A2A v1.0 Protobuf inputs/outputs in its interactive Swagger documentation, including dynamically prefixing OpenAPI paths with the rpc_url.
• JSON-RPC Server Simplification: The JSON-RPC server has been simplified by removing the custom A2AFastAPI class and now directly instantiates the base FastAPI class, as the a2a.json schema was incompatible with its requirements.

Changelog

• src/a2a/server/apps/jsonrpc/fastapi_app.py
  • Removed importlib.resources and json imports, which were no longer needed after the A2AFastAPI class was removed.
  • Deleted the A2AFastAPI class, which previously attempted to load a2a.json for OpenAPI schema generation.
  • Updated the build function to instantiate the base FastAPI class directly instead of the custom A2AFastAPI.
• src/a2a/server/apps/rest/fastapi_app.py
  • Added importlib.resources and json imports to support loading the a2a.json schema.
  • Introduced the A2AFastAPI class, which extends FastAPI and includes logic to load a2a.json for OpenAPI schema generation, and to prefix paths with rpc_url.
  • Modified the build function to instantiate the new A2AFastAPI class and assign the rpc_url to its instance.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request correctly refactors the OpenAPI schema generation by moving the logic that loads the a2a.json schema from the JSON-RPC application to the REST application. This aligns with the fact that the schema is only compatible with the REST transport. The new implementation in the REST application also correctly prepends the rpc_url to the schema paths. The changes are logical and well-executed. I have one minor suggestion to improve exception handling for better robustness and easier debugging.

[gemini-code-assist]

Catching a broad Exception is generally discouraged as it can hide unexpected errors. It's better to catch specific exceptions that you expect to handle, such as ImportError, OSError, and json.JSONDecodeError. This will make the code more robust and easier to debug. Additionally, logging the specific exception provides more context for troubleshooting.

Suggested change

	except Exception: # noqa: BLE001
	logger.warning(
	"Could not load 'a2a.json' from 'a2a.types'. Falling back to auto-generation."
	)
	except (ImportError, OSError, json.JSONDecodeError) as e:
	logger.warning(
	"Could not load 'a2a.json' from 'a2a.types'. Falling back to auto-generation: %s",
	e,
	)

[github-actions]

🧪 Code Coverage (vs 1.0-dev)

⬇️ Download Full Report

	Base	PR	Delta
src/a2a/server/apps/rest/fastapi_app.py	85.42%	58.23%	🔴 -27.19%
Total	90.22%	89.92%	🔴 -0.30%

Generated by coverage-comment.yml