OpenAPI Documentation Generation & Management

Use Dubbo-go’s built-in OpenAPI support to automatically generate and expose OpenAPI 3.0 documentation, with Swagger UI and ReDoc for visual API management.

Dubbo-go provides built-in OpenAPI support that automatically generates OpenAPI 3.0-compliant API documentation for Triple protocol services, with Swagger UI and ReDoc for visual API browsing and debugging.

Feature Overview

Automatic Documentation Generation: Automatically generates OpenAPI 3.0.1 API documentation based on service interface definitions (protobuf IDL or non-IDL mode)
Swagger UI: Built-in Swagger UI interface for online API browsing and debugging
ReDoc: Built-in ReDoc interface for clean API documentation presentation
Multiple Output Formats: Supports both JSON and YAML output formats
Group Management: Supports organizing services into OpenAPI Groups for managing multiple API versions
Static Documentation Generation: Generate static OpenAPI documentation files at compile time from .proto files using the protoc-gen-triple-openapi plugin

Quick Start

1. Enable OpenAPI

Enable OpenAPI through the Triple protocol options when creating a Server:

package main

import (
    "dubbo.apache.org/dubbo-go/v3/protocol"
    triple "dubbo.apache.org/dubbo-go/v3/protocol/triple"
    "dubbo.apache.org/dubbo-go/v3/server"
)

func main() {
    srv, err := server.NewServer(
        server.WithServerProtocol(
            protocol.WithTriple(
                triple.WithOpenAPI(
                    triple.OpenAPIEnable(),
                ),
            ),
            protocol.WithPort(20000),
        ),
    )
    if err != nil {
        panic(err)
    }
    // Register services...
    srv.Serve()
}

Once the service is started, you can access the OpenAPI documentation at the following endpoints:

Endpoint	Description
`http://localhost:20000/dubbo/openapi/swagger-ui/`	Swagger UI interface
`http://localhost:20000/dubbo/openapi/redoc/`	ReDoc interface
`http://localhost:20000/dubbo/openapi/openapi.json`	OpenAPI JSON format documentation
`http://localhost:20000/dubbo/openapi/openapi.yaml`	OpenAPI YAML format documentation
`http://localhost:20000/dubbo/openapi/api-docs/{group}.json`	JSON documentation for a specific group

2. Custom Configuration

You can customize various properties of the OpenAPI documentation:

srv, err := server.NewServer(
    server.WithServerProtocol(
        protocol.WithTriple(
            triple.WithOpenAPI(
                triple.OpenAPIEnable(),
                triple.OpenAPIInfoTitle("My API Service"),
                triple.OpenAPIInfoDescription("A service with OpenAPI documentation"),
                triple.OpenAPIInfoVersion("1.0.0"),
                triple.OpenAPIPath("/custom/openapi"),
            ),
        ),
        protocol.WithPort(20000),
    ),
)

Configuration Options

Option	Method	Default	Description
Enable OpenAPI	`OpenAPIEnable()`	`false`	Enable the OpenAPI feature
Document Title	`OpenAPIInfoTitle(title)`	`Dubbo-go OpenAPI`	Title of the API documentation
Document Description	`OpenAPIInfoDescription(desc)`	`Dubbo-go OpenAPI`	Description of the API documentation
Document Version	`OpenAPIInfoVersion(ver)`	`1.0.0`	Version of the API documentation
Base Path	`OpenAPIPath(path)`	`/dubbo/openapi`	URL prefix for OpenAPI endpoints
Consumes Media Types	`OpenAPIDefaultConsumesMediaTypes(types...)`	`["application/json"]`	Default Content-Type for request bodies
Produces Media Types	`OpenAPIDefaultProducesMediaTypes(types...)`	`["application/json"]`	Default Content-Type for response bodies
HTTP Status Codes	`OpenAPIDefaultHttpStatusCodes(codes...)`	`["200","400","500"]`	Default response status codes for each operation

Group Management

When you need to expose multiple versions of API documentation within the same application, you can use the OpenAPI group feature. With the server.WithOpenAPIGroup() option, you can register different services into different groups:

// Register service to the default group
demo.RegisterGreetServiceHandler(srv, &DemoTripleServerV1{},
    server.WithVersion("1.0.0"),
)

// Register service to the "demo-v2" group
demo.RegisterGreetServiceHandler(srv, &DemoTripleServerV2{},
    server.WithOpenAPIGroup("demo-v2"),
    server.WithVersion("2.0.0"),
)

Access group documentation:

Default group: http://localhost:20000/dubbo/openapi/api-docs/default.json
Specific group: http://localhost:20000/dubbo/openapi/api-docs/demo-v2.json

In Swagger UI, groups are displayed as a dropdown list, making it easy to switch between different API documentation groups.

Non-IDL Mode Support

In addition to protobuf IDL-based services, OpenAPI also supports non-IDL mode services. The framework automatically resolves struct fields and json tags via Go reflection to generate corresponding Schema definitions:

type UserService struct{}

type UserRequest struct {
    Id int32 `json:"id"`
}

type UserResponse struct {
    Id   int32  `json:"id"`
    Name string `json:"name"`
    Age  int32  `json:"age"`
}

func (u *UserService) GetUser(ctx context.Context, req *UserRequest) (*UserResponse, error) {
    return &UserResponse{
        Id:   req.Id,
        Name: "Alice",
        Age:  30,
    }, nil
}

func (u *UserService) Reference() string {
    return "com.example.UserService"
}

After registering the service, OpenAPI automatically generates JSON Schemas for UserRequest and UserResponse, including field names (from json tags) and type mappings.

Go Type to OpenAPI Schema Mapping

Go Type	OpenAPI Schema Type
`string`	`string`
`bool`	`boolean`
`int`, `int32`	`integer` (format: int32)
`int64`	`integer` (format: int64)
`float32`	`number` (format: float)
`float64`	`number` (format: double)
`[]T`	`array` (items: schema of T)
`map[string]T`	`object` (additionalProperties: schema of T)
`time.Time`	`string` (format: date-time)
`struct`	`object` (properties: schema of each field)

Static Documentation Generation (protoc-gen-triple-openapi)

In addition to runtime-generated online documentation, Dubbo-go provides the protoc-gen-triple-openapi tool for generating static OpenAPI documentation files (JSON/YAML) at compile time from .proto files. This is useful for integration into CI/CD pipelines or third-party API management platforms.

Installation

go install github.com/apache/dubbo-go/tools/protoc-gen-triple-openapi

Usage

Given a greet.proto file:

syntax = "proto3";

package greet;

option go_package = "github.com/apache/dubbo-go-samples/rpc/triple/openapi/proto/greet;greet";

message GreetRequest {
  string name = 1;
}

message GreetResponse {
  string greeting = 1;
}

service GreetService {
  rpc Greet(GreetRequest) returns (GreetResponse) {}
}

Run the following command to generate OpenAPI documentation:

protoc --triple-openapi_out=. greet.proto

This will generate a greet.triple.openapi.yaml file in the current directory with the following content:

openapi: 3.0.1
info:
  title: Dubbo-go OpenAPI
  description: dubbo-go generate OpenAPI docs.
  version: v1
servers:
  - url: http://0.0.0.0:20000
    description: Dubbo-go Default Server
paths:
  /greet.GreetService/Greet:
    post:
      tags:
        - greet.GreetService
      operationId: Greet
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/greet.GreetRequest'
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/greet.GreetResponse'
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error
components:
  schemas:
    greet.GreetRequest:
      type: object
      properties:
        name:
          type: string
    greet.GreetResponse:
      type: object
      properties:
        greeting:
          type: string

Customizing Swagger UI / ReDoc

You can customize the CDN URLs and UI settings for Swagger UI and ReDoc through OpenAPISettings:

triple.WithOpenAPI(
    triple.OpenAPIEnable(),
    triple.OpenAPISettings(map[string]string{
        "swagger-ui.cdn": "https://your-custom-cdn.com/swagger-ui-dist@5.18.2",
        "redoc.cdn":      "https://your-custom-cdn.com/redoc/latest/bundles",
        "swagger-ui.settings.filter": "true",
    }),
)

Supported settings keys:

Key	Description	Default
`swagger-ui.cdn`	CDN URL for Swagger UI	`https://unpkg.com/swagger-ui-dist@5.18.2`
`redoc.cdn`	CDN URL for ReDoc	`https://cdn.redoc.ly/redoc/latest/bundles`
`swagger-ui.settings.*`	Additional Swagger UI configuration options (injected into SwaggerUIBundle config)	None

Complete Example

Here is a complete example demonstrating various features:

package main

import (
    "context"

    _ "dubbo.apache.org/dubbo-go/v3/imports"
    "dubbo.apache.org/dubbo-go/v3/protocol"
    triple "dubbo.apache.org/dubbo-go/v3/protocol/triple"
    "dubbo.apache.org/dubbo-go/v3/server"
)

type GreetTripleServer struct{}

func (srv *GreetTripleServer) Greet(ctx context.Context, req *greet.GreetRequest) (*greet.GreetResponse, error) {
    return &greet.GreetResponse{Greeting: "Hello, " + req.Name}, nil
}

func main() {
    srv, err := server.NewServer(
        server.WithServerProtocol(
            protocol.WithTriple(
                triple.WithOpenAPI(
                    triple.OpenAPIEnable(),
                    triple.OpenAPIInfoTitle("OpenAPI Example Service"),
                    triple.OpenAPIInfoDescription("An example service with OpenAPI documentation"),
                    triple.OpenAPIInfoVersion("1.0.0"),
                ),
            ),
            protocol.WithPort(20000),
        ),
    )
    if err != nil {
        panic(err)
    }

    if err := greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{}); err != nil {
        panic(err)
    }

    if err := srv.Serve(); err != nil {
        panic(err)
    }
}

After starting, visit http://localhost:20000/dubbo/openapi/swagger-ui/ to view the Swagger UI documentation.

Architecture

The core architecture of Dubbo-go OpenAPI consists of the following components:

OpenAPIIntegration: The entry point for OpenAPI integration, responsible for initializing and coordinating all components
DefaultService: The core service that manages service registration, OpenAPI document generation, and caching
DefinitionResolver: Resolves and generates OpenAPI document definitions based on service information
SchemaResolver: Maps Go types to OpenAPI Schemas via Go reflection
RequestHandler: Handles HTTP requests for OpenAPI documents (JSON/YAML format output)
SwaggerUIHandler: Handles Swagger UI page requests
RedocHandler: Handles ReDoc page requests
Encoder: Encodes OpenAPI documents into JSON or YAML format

When a service is registered to the Server, the OpenAPI module collects metadata such as the service’s interface name, method information, and request/response types. Upon receiving a documentation request, the DefinitionResolver and SchemaResolver dynamically generate documentation that conforms to the OpenAPI 3.0 specification.