How to Add Swagger‑Like Documentation and Testing to Dubbo with Dubbo‑Api‑Docs

Dubbo‑Api‑Docs brings Swagger‑like documentation and testing capabilities to Dubbo services, addressing the lack of built‑in interface description in Dubbo‑Admin.

Background

Swagger (now OpenAPI) is a widely used framework for describing, visualizing, and testing RESTful APIs. Springfox integrates Swagger with Spring MVC/WebFlux to generate API docs automatically. Dubbo, being an RPC framework, does not support OpenAPI out of the box, so a custom solution is needed.

Why Dubbo‑Api‑Docs?

Existing tools either wrap Swagger JSON in a text area or generate simple forms from Java‑based OpenAPI generators, but they all require turning the provider into a web project and pulling in many web‑related dependencies. Dubbo‑Api‑Docs was created to provide a lightweight, annotation‑driven approach that works directly with Dubbo providers.

Implementation Overview

Provide a set of simple annotations to describe API metadata.

Parse these annotations at provider startup and cache the results.

Add Dubbo‑Api‑Docs specific provider interfaces for fetching API information.

Expose an HTTP gateway in Dubbo‑Admin to call Dubbo interfaces.

Display and test interfaces within Dubbo‑Admin.

Parameters of basic data types or beans with basic fields are rendered as form items; other parameters are shown as raw JSON.

Getting Started

Add the following Maven dependencies to your Dubbo project:

<dependency>
  <groupId>org.apache.dubbo</groupId>
  <artifactId>dubbo-api-docs-annotations</artifactId>
  <version>${dubbo-version}</version>
</dependency>

<dependency>
  <groupId>org.apache.dubbo</groupId>
  <artifactId>dubbo-api-docs-core</artifactId>
  <version>${dubbo-version}</version>
</dependency>

Annotate your service interface and method parameters with @ApiModule, @ApiDoc, @RequestParam, and @ResponseProperty. Example:

@DubboService
@ApiModule(value="quick start demo", apiInterface = IQuickStartDemo.class, version="v0.1")
public class QuickStartDemoImpl implements IQuickStartDemo {

  @ApiDoc(value="quick start demo", version="v0.1", description="this api is a quick start demo", responseClassDescription="A quick start response bean")
  @Override
  public QuickStartRespBean quickStart(@RequestParam(value="strParam", required=true) String strParam,
                                      QuickStartRequestBean beanParam) {
    return new QuickStartRespBean(200, "hello " + beanParam.getName() + ", " + beanParam.toString());
  }
}

Create a configuration class to enable the docs, preferably under a @Profile("dev") to avoid loading in production:

@Configuration
@Profile("dev")
@EnableDubboApiDocs
public class DubboDocConfig {}

Running the Example

Clone the example repository:

git clone -b 2.7 https://github.com/apache/dubbo-spi-extensions.git

Navigate to dubbo-api-docs-examples which contains two modules: examples-api (interface and bean definitions) and examples-provider (Spring Boot provider).

Add the annotations to the beans in examples-api (see code snippets above).

Start the provider with mvn spring-boot:run (or mvn -pl examples-provider spring-boot:run).

Setting Up Dubbo‑Admin

Clone the develop branch of Dubbo‑Admin:

git clone -b develop https://github.com/apache/dubbo-admin.git

Modify dubbo-admin-server/src/main/resources/application.properties to point to your registry (e.g., Nacos).

Build and run:

mvn clean package
mvn --projects dubbo-admin-server spring-boot:run
# or
cd dubbo-admin-distribution/target && java -jar dubbo-admin-0.1.jar

Open http://localhost:8080 (default credentials: root/root).

Enter the provider IP and port, click “Load Interface List”, then select an interface to view its documentation and test it via the generated form.

Annotation Reference

@EnableDubboApiDocs : Enables the Dubbo‑Api‑Docs feature.

@ApiModule : Class‑level annotation specifying module name, interface class, and version.

@ApiDoc : Method‑level annotation defining API name, description, version, and response description.

@RequestParam : Marks request parameters; supports value, required, description, example, defaultValue, and allowableValues.

@ResponseProperty : Marks response fields; supports value and example.

Usage Tips

Response beans may use a single generic placeholder.

Map keys must be primitive types; otherwise JSON generation fails.

Async settings are taken from org.apache.dubbo.config.annotation.Service#async or DubboService#async.

For more detailed examples and source code, refer to the dubbo-spi-extensions repository (branch 2.7.x) and the dubbo-api-docs-examples module.