Feature Request: Introduce .proto Feature Support in Swagger Editor (next)

[NYH-Dolphin]

Feature Request: Add .proto Syntax Support in Swagger Editor

Swagger Editor is an excellent tool for displaying and editing OpenAPI (Swagger) specifications. However, many modern backend and frontend architectures rely on gRPC and Protocol Buffers (.proto) for high-performance communication. To improve interoperability and expand Swagger Editor's capabilities, I propose adding support for .proto syntax, including previewing and converting .proto definitions into OpenAPI-compatible formats.

syntax = "proto3";

package stocki;

service StockService {
 rpc GetStockInfo (StockRequest) returns (StockResponse);

 rpc GetStockStream (StockStreamRequest) returns (stream StockResponse);

 rpc SubscribeStockPrice (StockRequest) returns (stream StockPriceUpdate);
}

message StockRequest {
 string symbol = 1; 
}

message StockStreamRequest {
 repeated string symbols = 1;
}

message StockResponse {
 string symbol = 1;
 string company_name = 2;
 double price = 3;
 double change = 4;
}

message StockPriceUpdate {
 string symbol = 1;
 double price = 2;
 string timestamp = 3;
}

Why Should Swagger Editor support .proto?

Growing Adoption of gRPC & Protobuf in API Design

• Many backend services and microservices are transitioning from REST to gRPC, leveraging its high performance, type safety, and bi-directional streaming.
• OpenAPI (Swagger) is widely used for REST, but many teams use both REST and gRPC, making it essential to have a unified API documentation tool.
• Supporting .proto in Swagger Editor would bridge the gap between REST and gRPC development, making it easier for teams to work with both protocols.

Unified API Documentation: Convert .proto to OpenAPI

• Swagger Editor is a great tool for API visualization. With .proto support, it could:
  • Parse and display .proto files directly in the editor.
  • Enable users to convert .proto to OpenAPI format for better API documentation.
  • Allow side-by-side comparison of OpenAPI and .proto formats.
• Existing tools like grpc-gateway and buf already allow conversion between Protocol Buffers and OpenAPI, making implementation feasible.

Improved Developer Workflow

• Developers frequently switch between REST and gRPC APIs.
• Currently, developers must use separate tools (e.g., buf, protoc, grpc-gateway) to work with .proto.
• Integrating .proto support directly into Swagger Editor would streamline API development and documentation.

Proposed Solution

Currently, I am working on a pipeline for converting .proto files to Swagger/OpenAPI (supporting 2.0, 3.0, and 3.1). This is currently implemented as a command-line solution, and I would like to integrate it into the Swagger Editor (next branch) for a more seamless developer experience.

Additionally, existing solutions such as protobuf.js provide efficient .proto parsing capabilities. By leveraging these tools, we can enable users to preview, edit, and convert .proto files directly within Swagger Editor, making it a unified platform for both OpenAPI and gRPC documentation.

There are no major technical barriers preventing this feature, as the core conversion logic is already well-supported by existing libraries. The main effort would involve integrating these capabilities into the Swagger Editor UI, ensuring a smooth user experience.

I am also stepping into the swagger-editor and attempting to introduce a proto-editor preview (which turns out to be a first success)

References & Related Work

• gRPC Official Docs: https://grpc.io/docs/
• Protocol Buffers Guide: https://protobuf.dev/programming-guides/proto3/
• buf (Modern Protobuf Tooling): https://buf.build/
• grpc-gateway (Protobuf → OpenAPI Conversion): https://github.com/grpc-ecosystem/grpc-gateway
• protobuf.js (JS Library for Protobuf Parsing): https://github.com/protobufjs/protobuf.js

Would like to learn more from the team 😄