feat: add openapi sample (#1063)

* feat: add openapi sample

* fix fmt

* panic

* fix ci

* add doc

Author: eye-gu

README.md

@@ -64,6 +64,7 @@ Please refer to [HOWTO.md](HOWTO.md) for detailed instructions on running the sa
   * `rpc/grpc`: gRPC protocol example.
   * `rpc/jsonrpc`: JSON-RPC protocol example.
   * `rpc/triple`: Triple protocol example with multiple serialization formats.
+  * `rpc/triple/openapi`: Demonstrates how to enable OpenAPI documentation for Triple protocol services, including versioned services and non-IDL services.
 * `streaming`: Streaming RPC example, also includes Go–Java interoperability when both use streaming.
 * `task`: Task scheduling and execution example.
 * `timeout`: Demonstrates timeout handling in Dubbo-go.

README_CN.md

@@ -64,6 +64,7 @@
   * `rpc/grpc`：基于 gRPC 协议的示例。
   * `rpc/jsonrpc`：基于 JSON-RPC 协议的示例。
   * `rpc/triple`：Triple 协议示例，涵盖多种序列化方式。
+  * `rpc/triple/openapi`：演示如何为 Triple 协议服务启用 OpenAPI 文档，包括多版本服务和非 IDL 服务的注册。
 * `streaming`：流式 RPC 调用示例，并包含了Dubbo-go与Dubbo-java同时使用流式传输的互操作示例。
 * `task`：任务调度与执行示例。
 * `timeout`：Dubbo-go 超时处理示例。

rpc/triple/openapi/README.md

@@ -0,0 +1,106 @@
+# Triple OpenAPI Sample
+
+English | [中文](README_CN.md)
+
+This sample demonstrates how to enable OpenAPI documentation for Triple protocol services in Dubbo-go. With OpenAPI enabled, the Triple server automatically generates and serves OpenAPI documentation in both JSON and YAML formats, and provides built-in Swagger UI and ReDoc pages for easy browsing and testing of your RPC services.
+
+## What It Covers
+
+- Enabling OpenAPI via `triple.OpenAPIEnable()` inside `triple.WithOpenAPI()`.
+- Registering multiple proto-based services (including streaming) with OpenAPI support.
+- Registering services with different versions and OpenAPI groups.
+- Registering a non-proto (non-IDL) service alongside proto-based services.
+
+## Contents
+
+- `go-server/cmd/main.go` - The server that enables OpenAPI and registers multiple services.
+- `go-client/cmd/main.go` - The client that calls the greet service (unary, server stream, client stream, bidi stream).
+- `proto/greet/greet.proto` - Protobuf definition with unary and streaming RPCs.
+- `proto/demo/demo.proto` - Protobuf definition for demonstrating versioned service registration.
+
+## How to Run
+
+### Start the Server
+
+```shell
+go run ./go-server/cmd/main.go
+```
+
+### Verify OpenAPI Documentation
+
+Once the server is running, you can access the OpenAPI documentation via the following URLs:
+
+| URL | Description |
+|-----|-------------|
+| `http://127.0.0.1:20000/dubbo/openapi/swagger-ui/` | Swagger UI page |
+| `http://127.0.0.1:20000/dubbo/openapi/openapi.json` | OpenAPI spec in JSON format |
+| `http://127.0.0.1:20000/dubbo/openapi/openapi.yaml` | OpenAPI spec in YAML format |
+| `http://127.0.0.1:20000/dubbo/openapi/api-docs/default.json` | Per-group OpenAPI spec (JSON) for the `default` group |
+| `http://127.0.0.1:20000/dubbo/openapi/api-docs/default.yaml` | Per-group OpenAPI spec (YAML) for the `default` group |
+| `http://127.0.0.1:20000/dubbo/openapi/redoc/index.html?group=default` | ReDoc documentation for the `default` group |
+
+For the `demo-2.0.0` group, replace `default` with `demo-2.0.0` in the URLs above.
+
+### Run the Client
+
+```shell
+go run ./go-client/cmd/main.go
+```
+
+## Configuration Reference
+
+### Server-side OpenAPI Configuration
+
+`triple.WithOpenAPI()` is the entry point for OpenAPI configuration. It accepts the following options:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `triple.OpenAPIEnable()` | Enable OpenAPI documentation generation. **Required** to activate OpenAPI. | `false` |
+| `triple.OpenAPIInfoTitle(title)` | Title of the OpenAPI document. | `"Dubbo-go OpenAPI"` |
+| `triple.OpenAPIInfoDescription(desc)` | Description of the OpenAPI document. | `"Dubbo-go OpenAPI"` |
+| `triple.OpenAPIInfoVersion(version)` | Version of the OpenAPI document. | `"1.0.0"` |
+| `triple.OpenAPIPath(path)` | Base URL path for serving OpenAPI endpoints. | `"/dubbo/openapi"` |
+| `triple.OpenAPIDefaultConsumesMediaTypes(types...)` | Default request content types. | `["application/json"]` |
+| `triple.OpenAPIDefaultProducesMediaTypes(types...)` | Default response content types. | `["application/json"]` |
+| `triple.OpenAPIDefaultHttpStatusCodes(codes...)` | Default HTTP status codes for responses. | `["200", "400", "500"]` |
+| `triple.OpenAPISettings(settings)` | Additional key-value settings. | `{}` |
+
+Example:
+
+```go
+srv, err := server.NewServer(
+    server.WithServerProtocol(
+        protocol.WithTriple(
+            triple.WithOpenAPI(
+                triple.OpenAPIEnable(),
+                triple.OpenAPIInfoTitle("OpenAPI Service"),
+                triple.OpenAPIInfoDescription("A service with OpenAPI documentation"),
+                triple.OpenAPIInfoVersion("1.0.0"),
+            ),
+        ),
+        protocol.WithPort(20000),
+    ),
+)
+```
+
+### Service-level OpenAPI Group
+
+When registering a service, you can assign it to a specific OpenAPI group via `server.WithOpenAPIGroup()`:
+
+```go
+demo.RegisterGreetServiceHandler(srv, &DemoTripleServerV2{},
+    server.WithOpenAPIGroup("demo-2.0.0"),
+    server.WithVersion("2.0.0"),
+)
+```
+
+Services without an explicit group fall into the `default` group.
+
+### Services Registered in This Sample
+
+| Service | Description |
+|---------|-------------|
+| `greet.GreetService` | Unary + streaming RPCs (server stream, client stream, bidi stream) |
+| `demo.GreetService` (v1.0.0) | Unary RPC with version `1.0.0` |
+| `demo.GreetService` (v2.0.0) | Same interface with version `2.0.0`, registered under OpenAPI group `demo-2.0.0` |
+| `com.example.UserService` | Non-proto (non-IDL) service, registered without protobuf |

rpc/triple/openapi/README_CN.md

@@ -0,0 +1,106 @@
+# Triple OpenAPI 示例
+
+[English](README.md) | 中文
+
+本示例演示如何在 Dubbo-go 中为 Triple 协议服务启用 OpenAPI 文档。启用 OpenAPI 后，Triple 服务端会自动生成并提供 JSON 和 YAML 两种格式的 OpenAPI 文档，同时内置 Swagger UI 和 ReDoc 页面，方便浏览和测试 RPC 服务。
+
+## 功能说明
+
+- 通过 `triple.OpenAPIEnable()` 在 `triple.WithOpenAPI()` 中启用 OpenAPI 文档。
+- 注册多个基于 Protobuf 的服务（包括流式 RPC），并支持 OpenAPI 文档。
+- 注册不同版本的服务，并使用不同的 OpenAPI 分组。
+- 在基于 Protobuf 的服务之外，注册非 Protobuf（非 IDL）的服务。
+
+## 目录结构
+
+- `go-server/cmd/main.go` - 启用 OpenAPI 并注册多个服务的服务端。
+- `go-client/cmd/main.go` - 调用 Greet 服务的客户端（Unary、Server Stream、Client Stream、Bidi Stream）。
+- `proto/greet/greet.proto` - 包含 Unary 和流式 RPC 的 Protobuf 定义。
+- `proto/demo/demo.proto` - 用于演示多版本服务注册的 Protobuf 定义。
+
+## 运行方法
+
+### 启动服务端
+
+```shell
+go run ./go-server/cmd/main.go
+```
+
+### 验证 OpenAPI 文档
+
+服务启动后，可以通过以下地址访问 OpenAPI 文档：
+
+| URL | 说明 |
+|-----|------|
+| `http://127.0.0.1:20000/dubbo/openapi/swagger-ui/` | Swagger UI 页面 |
+| `http://127.0.0.1:20000/dubbo/openapi/openapi.json` | JSON 格式的 OpenAPI 规范 |
+| `http://127.0.0.1:20000/dubbo/openapi/openapi.yaml` | YAML 格式的 OpenAPI 规范 |
+| `http://127.0.0.1:20000/dubbo/openapi/api-docs/default.json` | `default` 分组的 OpenAPI 规范（JSON） |
+| `http://127.0.0.1:20000/dubbo/openapi/api-docs/default.yaml` | `default` 分组的 OpenAPI 规范（YAML） |
+| `http://127.0.0.1:20000/dubbo/openapi/redoc/index.html?group=default` | `default` 分组的 ReDoc 文档 |
+
+对于 `demo-2.0.0` 分组，将上述 URL 中的 `default` 替换为 `demo-2.0.0` 即可。
+
+### 启动客户端
+
+```shell
+go run ./go-client/cmd/main.go
+```
+
+## 配置说明
+
+### 服务端 OpenAPI 配置
+
+`triple.WithOpenAPI()` 是 OpenAPI 配置的入口，接受以下选项：
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `triple.OpenAPIEnable()` | 启用 OpenAPI 文档生成，**必须调用**才能激活 OpenAPI。 | `false` |
+| `triple.OpenAPIInfoTitle(title)` | OpenAPI 文档标题。 | `"Dubbo-go OpenAPI"` |
+| `triple.OpenAPIInfoDescription(desc)` | OpenAPI 文档描述。 | `"Dubbo-go OpenAPI"` |
+| `triple.OpenAPIInfoVersion(version)` | OpenAPI 文档版本。 | `"1.0.0"` |
+| `triple.OpenAPIPath(path)` | OpenAPI 端点的 URL 基础路径。 | `"/dubbo/openapi"` |
+| `triple.OpenAPIDefaultConsumesMediaTypes(types...)` | 默认请求内容类型。 | `["application/json"]` |
+| `triple.OpenAPIDefaultProducesMediaTypes(types...)` | 默认响应内容类型。 | `["application/json"]` |
+| `triple.OpenAPIDefaultHttpStatusCodes(codes...)` | 默认响应 HTTP 状态码。 | `["200", "400", "500"]` |
+| `triple.OpenAPISettings(settings)` | 额外的键值对配置。 | `{}` |
+
+示例：
+
+```go
+srv, err := server.NewServer(
+    server.WithServerProtocol(
+        protocol.WithTriple(
+            triple.WithOpenAPI(
+                triple.OpenAPIEnable(),
+                triple.OpenAPIInfoTitle("OpenAPI Service"),
+                triple.OpenAPIInfoDescription("A service with OpenAPI documentation"),
+                triple.OpenAPIInfoVersion("1.0.0"),
+            ),
+        ),
+        protocol.WithPort(20000),
+    ),
+)
+```
+
+### 服务级 OpenAPI 分组
+
+注册服务时，可以通过 `server.WithOpenAPIGroup()` 将服务分配到指定的 OpenAPI 分组：
+
+```go
+demo.RegisterGreetServiceHandler(srv, &DemoTripleServerV2{},
+    server.WithOpenAPIGroup("demo-2.0.0"),
+    server.WithVersion("2.0.0"),
+)
+```
+
+未显式指定分组的服务会归入 `default` 分组。
+
+### 本示例注册的服务
+
+| 服务 | 说明 |
+|------|------|
+| `greet.GreetService` | Unary + 流式 RPC（Server Stream、Client Stream、Bidi Stream） |
+| `demo.GreetService` (v1.0.0) | 版本为 `1.0.0` 的 Unary RPC |
+| `demo.GreetService` (v2.0.0) | 相同接口但版本为 `2.0.0`，注册在独立的 OpenAPI 分组 `demo-2.0.0` 下 |
+| `com.example.UserService` | 非 Protobuf（非 IDL）服务，不依赖 Protobuf 定义 |

rpc/triple/openapi/go-client/cmd/main.go

@@ -0,0 +1,103 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"strings"
+)
+
+import (
+	"dubbo.apache.org/dubbo-go/v3/client"
+	_ "dubbo.apache.org/dubbo-go/v3/imports"
+)
+
+import (
+	greet "github.com/apache/dubbo-go-samples/rpc/triple/openapi/proto/greet"
+)
+
+func main() {
+	cli, err := client.NewClient(
+		client.WithClientURL("127.0.0.1:20000"),
+	)
+	if err != nil {
+		panic(err)
+	}
+	svc, err := greet.NewGreetService(cli)
+	if err != nil {
+		panic(err)
+	}
+
+	// Unary
+	resp, err := svc.Greet(context.Background(), &greet.GreetRequest{Name: "openapi"})
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("Greet response: %s\n", resp.Greeting)
+
+	// Server Stream
+	serverStream, err := svc.GreetServerStream(context.Background(), &greet.GreetServerStreamRequest{Name: "openapi"})
+	if err != nil {
+		panic(err)
+	}
+	for serverStream.Recv() {
+		msg := serverStream.Msg()
+		fmt.Printf("GreetServerStream response: %s\n", msg.Greeting)
+	}
+
+	// Client Stream
+	clientStream, err := svc.GreetClientStream(context.Background())
+	if err != nil {
+		panic(err)
+	}
+	for _, name := range []string{"alice", "bob", "charlie"} {
+		if sendErr := clientStream.Send(&greet.GreetClientStreamRequest{Name: name}); sendErr != nil {
+			panic(sendErr)
+		}
+	}
+	clientResp, err := clientStream.CloseAndRecv()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("GreetClientStream response: %s\n", clientResp.Greeting)
+
+	// Bidi Stream
+	bidiStream, err := svc.GreetBidiStream(context.Background())
+	if err != nil {
+		panic(err)
+	}
+	for _, name := range []string{"dave", "eve"} {
+		if err := bidiStream.Send(&greet.GreetBidiStreamRequest{Name: name}); err != nil {
+			panic(err)
+		}
+	}
+	if err := bidiStream.CloseRequest(); err != nil {
+		panic(err)
+	}
+	for {
+		msg, err := bidiStream.Recv()
+		if err != nil && strings.Contains(err.Error(), "EOF") {
+			break
+		}
+		if err != nil {
+			panic(err)
+		}
+		fmt.Printf("GreetBidiStream response: %s\n", msg.Greeting)
+	}
+}