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

[eye-gu]

close #6338

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.

[moremind]

else {? how to resolve?}

[eye-gu]

@moremind I think when document is blank or docItem is null, it means the API has no document data, so the page simply won't display any API Doc content — which is the expected behavior. The null checks (StringUtils.isNotBlank + Objects.nonNull) added in this PR already make the code safer than before. No additional else branch is needed here.

[Copilot]

Pull request overview

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