Skip to content

Website content en overview mannual golang sdk tutorial rpc openapi

Jump to bottom
alanxtl edited this page Sep 20, 2026 · 1 revision

OpenAPI Documentation Generation & Management

Go SDK 手册（版本需核对）。原文按来源版本保留；使用前请读 版本与升级。 来源：原文 · 提交 84b35ebdab20 · 返回目录

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.

Sample source: dubbo-go-samples/rpc/triple/openapi.

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.

首页 · 专题导读 · 版本与升级 · 来源 · 历史档案

资料快照：2026-09-20

Apache Dubbo-go

完整资料库

维护

Clone this wiki locally