marsevilspirit opened a new pull request, #2951:
URL: https://github.com/apache/dubbo-go/pull/2951
## PR Summary
This PR introduces a new `protoc` code generation plugin:
**`protoc-gen-triple-openapi`**. This plugin aims to provide a standardized
solution for automatically generating **OpenAPI v3** specifications for
Dubbo-go's Triple protocol at **compile-time**, thereby greatly enhancing API
discoverability, documentation, and interoperability.
Unlike the approach of dynamically generating documentation at runtime, this
plugin follows the design philosophy of the gRPC ecosystem (e.g.,
`protoc-gen-go`). It generates static OpenAPI specification files directly from
`.proto` source files during the build process, achieving **zero runtime
overhead** and facilitating easy version control and CI/CD integration.
## Core Features & Advantages
* **Compile-time Generation**: Runs as a `protoc` plugin to generate
static API specification files before the code is compiled. This ensures zero
impact on service performance, and the output is stable and predictable.
* **Native Protobuf Parsing**: Directly parses `.proto` files, accurately
mapping Protobuf elements like `Service`, `Method`, and `Message` to their
corresponding structures in the OpenAPI v3 specification, such as `Path`,
`Operation`, and `Schema`.
* **Full OpenAPI v3 Support**: Fully embraces the OpenAPI v3.0
specification, which offers richer and more powerful type expression
capabilities (e.g., `oneOf`, `anyOf`) compared to v2, allowing for a more
accurate description of gRPC API models.
* **Flexible Output Formats**: Supports generating specification files in
either `YAML` or `JSON` format via parameters, catering to different toolchains
and preferences.
* **Configuration-driven & Easy to Use**: The output is controlled by
simple command-line arguments, requiring no changes to business logic and
making it non-intrusive to existing projects.
## Usage Guide & Example
Integrating and using this plugin is a simple process that only takes a few
steps.
#### 1\. Prepare Your `.proto` File
This is the input source for the plugin. Below is an example `greet.proto`:
```proto
syntax = "proto3";
package greet;
option go_package =
"github.com/apache/dubbo-go/tools/protoc-gen-triple-openapi/example;greet";
message GreetRequest {
string name = 1;
}
message GreetResponse {
string greeting = 1;
}
// ... other message definitions
service GreetService {
rpc Greet(GreetRequest) returns (GreetResponse) {}
rpc GreetUser(GreetUserRequest) returns (GreetUserResponse) {}
}
```
#### 2. Install the Plugin
First, ensure the `protoc-gen-triple-openapi` plugin is installed and
available in your `PATH` environment variable.
```bash
go install dubbo.apache.org/dubbo-go/v3/cmd/protoc-gen-triple-openapi@latest
```
#### 3. Run the Command to Generate the Specification
Use the `protoc` command and specify `triple-openapi_out` to generate the
documentation.
* **Generate the default YAML file**:
```bash
# This command will generate greet.triple.openapi.yaml in the current
directory
protoc --triple-openapi_out=. greet.proto
```
* **Specify the output format (JSON or YAML)**:
You can flexibly control the output format using the
`--triple-openapi_opt` parameter.
```bash
# Generate JSON format
protoc --triple-openapi_out=. --triple-openapi_opt=format=json
greet.proto
# Explicitly generate YAML format
protoc --triple-openapi_out=. --triple-openapi_opt=format=yaml
greet.proto
```
#### 4\. Review and Use the Generated Specification
After the command executes successfully, you will get a
`*.triple.openapi.yaml` or `*.triple.openapi.json` file.
Below is an example of the `YAML` file content generated from the
`greet.proto` above:
```yaml
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'
# ... other content
components:
schemas:
greet.GreetRequest:
type: object
properties:
name:
type: string
title: name
title: GreetRequest
# ... other content
```
Afterward, you can use this static specification file with any tool that
supports OpenAPI v3 (such as **Swagger UI, Redoc, Postman**) for online API
documentation, debugging, and team collaboration.
This plugin is designed to provide Dubbo-go users with a powerful,
efficient, and community-standard tool for API documentation automation.
### **Future Goals**
- [ ] Provide built-in support for serving Swagger UI directly from the
Dubbo-go application.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@dubbo.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscr...@dubbo.apache.org
For additional commands, e-mail: notifications-h...@dubbo.apache.org
