One‑Click OpenAPI Generation with Apache Dubbo 3.3.3 and Apifox Integration

Background

In microservice environments, RPC service documentation, testing, and collaborative calls are often bottlenecks because RPC definitions and protocols vary and lack a universal standard. Apache Dubbo 3.3.3 embeds full compatibility with the Swagger OpenAPI 3 specification, allowing automatic generation of OpenAPI documents directly from Dubbo service interfaces.

Key Benefits

Eliminates the need for third‑party tools or extra configuration.

Provides seamless REST support via Dubbo’s Triple protocol, simplifying OpenAPI generation.

Reduces manual documentation effort by generating specs from code.

Keeps documentation synchronized with code changes.

Supports multi‑language environments through Proto format export.

Core Features

Automatic OpenAPI document generation from Dubbo interfaces.

Export options: JSON, YAML, and Protocol Buffers (Proto).

Built‑in Swagger UI reachable at /dubbo/openapi.

Real‑time synchronization of docs with service updates.

One‑click import of generated specs into tools such as Apifox.

Getting Started

Step 1 – Add Maven Dependency

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-rest-openapi</artifactId>
    <version>3.3.3</version>
</dependency>

Step 2 – Enable OpenAPI in application.yaml

dubbo:
  application:
    name: ${spring.application.name}
    qos-enable: false
  protocol:
    name: tri
    port: 50052
    triple:
      rest:
        openapi:
          enabled: true

Step 3 – Access the Generated Docs

Swagger UI: http://<host>:<port>/dubbo/openapi OpenAPI JSON: http://<host>:<port>/dubbo/openapi/api-docs YAML: http://<host>:<port>/dubbo/openapi/api-docs.yaml Proto:

http://<host>:<port>/dubbo/openapi/api-docs.proto

Advanced Customization with Annotations

@OpenAPI

@OpenAPI(
    infoTitle = "Dubbo OpenAPI",
    infoDescription = "This API provides greeting services for users.",
    infoVersion = "v1",
    docDescription = "API for greeting users with their names and titles."
)
public class DemoServiceImpl implements DemoService {
    // service methods
}

@Operation

@Operation(description = "Returns a greeting message with the provided name.")
@Override
public String hello(@Schema(description = "Name of the person to greet") String name) {
    return "Hello " + name;
}

@Schema

@Schema(title = "User Model", description = "Represents user information")
public class User {
    @Schema(title = "Username", example = "Tom")
    private String name;
}

Filtering Generated Docs

By group:

http://<host>:<port>/dubbo/openapi/api-docs/{group}

By version:

http://<host>:<port>/dubbo/openapi/api-docs?version=1.0.0

By tag:

http://<host>:<port>/dubbo/openapi/api-docs?tag=user,order

Sample Repository

https://github.com/apache/dubbo-samples/tree/master/2-advanced/dubbo-samples-triple-rest