Integrating Swagger with Dubbo for API Documentation and Testing

Dubbo is a high‑performance RPC framework provided by Alibaba, while Swagger (based on the OpenAPI specification) offers tools for designing, building, and documenting REST APIs. Swagger‑Dubbo combines these concepts to generate Swagger‑style documentation and provide HTTP‑style mock testing for Dubbo services.

Why Swagger‑Dubbo is Needed

Dubbo lacks built‑in documentation and testing UI similar to Swagger/Springfox. Swagger‑Dubbo fills this gap by exposing Dubbo interfaces as Swagger documentation and allowing HTTP‑based testing without writing separate docs.

Brief Introduction to Swagger

Swagger is positioned as an API construction tool with four main capabilities:

API design – edit and declare API interfaces.

Code generation – generate scaffolding code for various languages.

Documentation – generate formatted docs from code annotations.

Testing – use swagger‑ui to invoke and test APIs directly.

Swagger‑Dubbo Features

Swagger‑Dubbo provides Swagger‑style documentation and REST‑style HTTP mock testing, enabling developers to read interface docs, self‑test services, simulate other services' responses, and verify correctness via HTTP calls. It is intended for internal development and testing, not for exposing REST services to front‑end users.

Quick Integration

API layer dependency:

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-annotations</artifactId>
  <version>1.5.16</version>
</dependency>

Provider layer dependencies:

<dependency>
  <groupId>com.deepoove</groupId>
  <artifactId>swagger-dubbo</artifactId>
  <version>2.0.1_update</version>
</dependency>

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.5</version>
</dependency>

Java configuration (provider side):

package cn.xdf.activity.config;

import com.deepoove.swagger.dubbo.annotations.EnableDubboSwagger;
import java.util.List;
import org.apache.dubbo.config.spring.context.annotation.DubboComponentScan;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.context.annotation.Profile;
import org.springframework.core.env.Environment;
import springfox.documentation.spring.web.DocumentationCache;
import springfox.documentation.swagger.web.InMemorySwaggerResourcesProvider;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@DubboComponentScan(basePackages = { "cn.xdf.activity" })
@EnableDubboSwagger
@EnableSwagger2
@Profile(value = {"dev", "test"})
public class DubboConfig {

    @Bean
    @Primary
    public SwaggerResourcesProvider newSwaggerResourcesProvider(Environment env, DocumentationCache documentationCache) {
        return new InMemorySwaggerResourcesProvider(env, documentationCache) {

            @Override
            public List<SwaggerResource> get() {
                // 1. Call parent implementation
                List<SwaggerResource> resources = super.get();
                // 2. Add swagger‑dubbo resource
                SwaggerResource dubboSwaggerResource = new SwaggerResource();
                dubboSwaggerResource.setName("dubbo");
                dubboSwaggerResource.setSwaggerVersion("2.0");
                dubboSwaggerResource.setUrl("/swagger-dubbo/api-docs");
                dubboSwaggerResource.setLocation("/swagger-dubbo/api-docs"); // deprecated, same as url
                resources.add(0, dubboSwaggerResource);
                return resources;
            }
        };
    }
}

Swagger annotations can be added to Dubbo services:

@Api(value = "帐号服务")
@ApiOperation(value = "登出", notes = "退出用户信息")
@ApiParam(value = "用户帐号")

Additional configuration for YApi (as a unified API management platform) can be added to the service’s configuration file:

swagger:
  dubbo:
    http: h
    application:
      version: 1.0
      groupId: com.xdf
      artifactId: dubbo.activity-bigdata-service
    cluster: rpc
    enable: true

Running and Verifying

After starting the application, open http://127.0.0.1:20021/swagger-dubbo/api-docs to see the generated JSON documentation. Access http://127.0.0.1:20021/doc.htm to view the Swagger UI (enhanced by Knife4j). Select any interface, input parameters, and click “Send” to test the RPC call and view the response.

Integration with YApi

The generated documentation can be imported into YApi, providing a unified view and testing capabilities for all Dubbo services.

Underlying Principle

Swagger‑Dubbo uses Dubbo’s Java API to obtain the corresponding Dubbo consumer object, maps HTTP request parameters to Dubbo RPC parameters, and invokes the RPC call—see the DubboHttpController class for details.

Conclusion

By combining open‑source projects (Swagger‑Dubbo, Knife4j, YApi), developers can achieve automatic Dubbo API documentation, a powerful UI for browsing and testing, and centralized API management, greatly improving internal development and testing efficiency.