feat(api-doc): support request parameter parsing for RPC types (Dubbo/SOFA/TARS/gRPC)

[eye-gu]

close #6338
close #5940

Previously, API document generation only supported Spring Web annotation-based parameter parsing (@RequestParam, @RequestPart, path variables), which only works for HTTP/WebSocket/Spring Cloud. RPC types (Dubbo, SOFA, TARS, gRPC) had no request parameter information in generated documents.

Changes

OpenApiUtils - RPC-aware document generation

• Add buildDocumentJson() that dispatches by RPC type:
  • Dubbo/TARS: parse request parameters from Java method signatures
  • gRPC: parse request/response from StreamObserver method pattern
  • Dubbo + Protobuf: parse protobuf message fields via reflection for both request and response
  • HTTP/WebSocket/Spring Cloud: unchanged Spring MVC annotation parsing
• Unify document fields to requestParameters / responseParameters

SOFA - enable API document support

• Refactor SofaServiceEventListener to extend AbstractContextRefreshedEventListener common flow
• Replace custom handler() / onApplicationEvent() with standard getCorrectedClass() + buildApiPath() hooks
• SOFA services now go through the unified API doc registration pipeline

Examples

• Add @ApiModule / @ApiDoc annotations to Dubbo protobuf example services

Impact

• Dubbo/SOFA/TARS/gRPC API documents now include detailed request parameter schemas
• SOFA module gains API document generation capability
• No breaking change for HTTP/WebSocket/Spring Cloud document generation

Make sure that:

• You have read the contribution guidelines.
• You submit test cases (unit or integration tests) that back your changes.
• Your local test passed ./mvnw clean install -Dmaven.javadoc.skip=true.

[Copilot]

Pull request overview

This PR extends ShenYu’s API document generation so RPC-style services (Dubbo/SOFA/TARS/gRPC, including Dubbo protobuf) can produce request parameter schemas in generated API docs, and it aligns document field naming across protocols.

Changes:

• Add RPC-aware document generation in OpenApiUtils (RPC + gRPC request parsing, RPC-specific response generation, protobuf message field reflection).
• Route API doc registrars/listeners to the new unified requestParameters / responseParameters document structure.
• Add/adjust tests and example annotations; update build/checkstyle config to support generated protobuf test sources.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
shenyu-client/shenyu-client-core/src/main/java/org/apache/shenyu/client/core/utils/OpenApiUtils.java	Adds RPC/gRPC/protobuf-aware doc building and unifies document fields
shenyu-client/shenyu-client-core/src/main/java/org/apache/shenyu/client/core/register/registrar/ApiDocRegistrarImpl.java	Switches document generation to RPC-type dispatch via OpenApiUtils.buildDocumentJson
shenyu-client/shenyu-client-core/src/main/java/org/apache/shenyu/client/core/register/registrar/AbstractApiDocRegistrar.java	Uses new unified document builder for generated docs
shenyu-client/shenyu-client-core/src/main/java/org/apache/shenyu/client/core/client/AbstractContextRefreshedEventListener.java	Threads RPC type into doc generation for annotation-based docs
shenyu-client/shenyu-client-sofa/src/main/java/org/apache/shenyu/client/sofa/SofaServiceEventListener.java	Refactors SOFA listener into the shared refreshed-event flow to enable API doc pipeline
shenyu-client/shenyu-client-sofa/src/test/java/org/apache/shenyu/client/sofa/SofaServiceEventListenerTest.java	Updates test to align with the new path-building flow
shenyu-client/shenyu-client-core/src/test/java/org/apache/shenyu/client/core/utils/OpenApiUtilsTest.java	Adds extensive unit coverage for RPC/gRPC/protobuf parsing and dispatch
shenyu-client/shenyu-client-core/src/test/java/org/apache/shenyu/client/core/register/registrar/NoHttpApiDocRegistrarTest.java	Adds coverage that RPC/gRPC docs include request/response parameter fields
shenyu-client/shenyu-client-core/src/test/java/org/apache/shenyu/client/core/register/registrar/ApiDocRegistrarImplTest.java	Validates registrar document output uses unified field names across RPC types
shenyu-client/shenyu-client-core/src/test/proto/test.proto	Adds proto used by protobuf reflection tests
shenyu-client/shenyu-client-core/pom.xml	Adds test-only protobuf/grpc deps and proto generation for tests
shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/ApiServiceImpl.java	Parses doc JSON when present (not only SWAGGER source) to populate request/response parameter lists
shenyu-admin/src/test/java/org/apache/shenyu/admin/service/ApiServiceTest.java	Adds coverage for findById behavior with blank/non-blank document
shenyu-examples/.../DubboProtobufServiceImpl.java (3 files)	Adds @ApiModule/@ApiDoc annotations to protobuf Dubbo examples
pom.xml	Excludes generated sources from checkstyle to accommodate generated protobuf test code

Comments suppressed due to low confidence (1)

shenyu-client/shenyu-client-core/src/main/java/org/apache/shenyu/client/core/utils/OpenApiUtils.java:135

• generateRequestDocParameters currently parses either query parameters (when any @RequestParam/@RequestPart is present) or path template variables, but not both due to the if (...) { ... } else { ... } structure. This will drop {var} path parameters for endpoints that also have query params. Consider always parsing path segments and then merging/deduplicating with any query-derived parameters.

        List<Parameter> list = new ArrayList<>();
        Pair<Boolean, Annotation[][]> query = isQuery(method);
        if (query.getLeft()) {
            for (Annotation[] annotations : query.getRight()) {
                if (annotations.length > 0 && isQueryName(annotations[0].annotationType().getName(), QUERY_CLASSES)) {
                    for (Annotation annotation : annotations) {

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

[Aias00]

Following up on this PR. Head consistency check first: the effective diff against master is empty — gh pr diff 6339 and gh api pulls/6339/files both return nothing, and pr-6339^{tree} equals the master base tree b94a6997b. Tracing this, the PR's content was already squash-merged via #6379 (commit ca83c6974, merged 2026-06-12), whose body lists every commit on this branch. So all seven existing review threads are auto-resolved/outdated (the lines they referenced no longer exist in any diff). The remaining CHANGES_REQUESTED and BEHIND states are stale. Recommendation: close this PR and track follow-ups separately, since merging #6339 as-is is a no-op.

For the already-landed code on master, two follow-up issues worth a separate issue/PR:

1. Response-side repeated protobuf message fields lose nested schemas. In OpenApiUtils.parseRepeatedProtobufField (OpenApiUtils.java:521-541), a repeated MESSAGE field sets elementType.setType("object") + setDescription(fullMsgName) but never recurses or sets refs, so the element has no inner field schema. The request-side equivalent parseRepeatedProtobufFieldSchema (:917-936) does call resolveProtobufMessageFieldSchema and recurses. OpenApiUtilsTest.java:145-149 only asserts getType()=="object" on the addresses element and never checks nested getRefs(), so the gap is untested. Suggested fix: mirror the request side by calling resolveProtobufMessageField(elementType, ...) for the MESSAGE branch and add a test asserting street/city on the repeated-message response element.

2. Inherited DTO fields are omitted. parseClass (:692) and parseClassSchema (:803), plus the parameterized variants (:731, :841), iterate only getDeclaredFields() with no superclass walk, so RPC request/response DTOs that extend a base class drop base-class fields from the generated doc. Suggested fix: walk getSuperclass() up to Object/framework bases and accumulate fields; add a test with a DTO extending a base DTO.

Minor: array element naming is ITEMS on the response side (:668, :714) but items on the request/schema side (:827, :931) — pick one (lowercase items matches OpenAPI) for consistency.

The SOFA listener refactor (SofaServiceEventListener) and the handleClass→buildApiPath(method, superPath, null) flow look correct — the parent only enters handleClass when superPath.contains("*"), so the @Nullable third argument is never dereferenced on the non-wildcard branch.

[eye-gu]

@Aias00 PTAL.