feat: generate OpenAPI v3 spec (#34)

Author: seanmcgary

.gitignore

@@ -3,3 +3,5 @@
 *.sw*
 node_modules
 !gen
+/buf-plugin-openapi/bin
+/openapi-debug.log

Makefile

@@ -20,9 +20,12 @@ deps/go:
 	${GO} mod tidy
 	npm install
 
+pre-build:
+	cd protocol-apis-annotations && make proto
+	cd buf-plugin-openapi && make install
 
 .PHONY: proto
-proto:
+proto: pre-build
 	rm -rf gen/python || true
 	rm -rf gen/pre-python || true
 	buf generate protos

buf-plugin-openapi/Makefile

@@ -0,0 +1,42 @@
+.PHONY: build clean test install generate
+
+# Binary name
+BINARY_NAME=protoc-gen-buf-plugin-openapi
+
+# Build directory
+BUILD_DIR=./bin
+
+# Go build flags
+GO_BUILD_FLAGS=-v
+
+# Installation directory (this should be in your PATH)
+INSTALL_DIR=$(HOME)/.gvm/pkgsets/go1.23.6/global/bin
+
+# Ensure build directory exists
+$(BUILD_DIR):
+	mkdir -p $(BUILD_DIR)
+
+# Build the binary
+build: $(BUILD_DIR)
+	go build $(GO_BUILD_FLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)
+
+# Install the binary to GOPATH/bin for buf to find it
+install: build-all
+	mkdir -p $(INSTALL_DIR)
+	cp $(BUILD_DIR)/$(BINARY_NAME) $(INSTALL_DIR)/protoc-gen-buf-plugin-openapi
+
+# Clean build artifacts
+clean:
+	rm -rf $(BUILD_DIR)
+
+# Test the plugin with buf
+test: install
+	cd .. && buf generate
+
+PLUGIN_NAME := buf-plugin-openapi
+
+generate:
+	protoc --go_out=. --go_opt=paths=source_relative proto/annotations.proto
+
+.PHONY: build-all
+build-all:  build

buf-plugin-openapi/README.md

@@ -0,0 +1,79 @@
+# buf-plugin-openapi
+
+A [buf](https://buf.build) plugin that generates OpenAPI v3 specifications from Protocol Buffer definitions. This plugin is designed to work with gRPC-Gateway annotations to create accurate OpenAPI/Swagger documentation.
+
+## Features
+
+- Generates OpenAPI v3.0.0 specifications from Protocol Buffer definitions
+- Supports gRPC-Gateway HTTP annotations
+- Converts Protocol Buffer types to OpenAPI types
+- Handles path parameters and query parameters
+- Supports JSON field name customization
+- Generates proper request/response schemas
+
+## Installation
+
+```bash
+go install github.com/seanmcgary/buf-plugin-openapi@latest
+```
+
+## Usage
+
+Add the plugin to your `buf.yaml`:
+
+```yaml
+version: v1
+deps:
+  - buf.build/googleapis/googleapis
+  - buf.build/grpc-ecosystem/grpc-gateway
+plugins:
+  - plugin: buf-plugin-openapi
+    out: gen/openapi
+    opt:
+      - emit_defaults=true
+      - json_names_for_fields=true
+```
+
+Available options:
+
+- `emit_defaults`: Include default values in the OpenAPI output (default: true)
+- `omit_enum_default_value`: Omit default values for enum types (default: false)
+- `enums_as_ints`: Render enum values as integers instead of strings (default: false)
+- `simple_operation_ids`: Remove the service prefix from operation IDs (default: false)
+- `json_names_for_fields`: Use JSON names for fields instead of proto names (default: true)
+
+## Example
+
+Given a Protocol Buffer definition with gRPC-Gateway annotations:
+
+```protobuf
+syntax = "proto3";
+
+package example.v1;
+
+import "google/api/annotations.proto";
+
+service ExampleService {
+  rpc GetExample(GetExampleRequest) returns (GetExampleResponse) {
+    option (google.api.http) = {
+      get: "/v1/examples/{id}"
+    };
+  }
+}
+
+message GetExampleRequest {
+  string id = 1;
+}
+
+message GetExampleResponse {
+  string id = 1;
+  string name = 2;
+  int32 count = 3;
+}
+```
+
+The plugin will generate an OpenAPI v3 specification with proper paths, parameters, and schemas.
+
+## License
+
+MIT 

buf-plugin-openapi/go.mod

@@ -0,0 +1,13 @@
+module github.com/Layr-Labs/buf-plugin-openapi
+
+go 1.23.6
+
+require (
+	github.com/Layr-Labs/protocol-apis-annotations v0.0.0-00010101000000-000000000000
+	google.golang.org/genproto/googleapis/api v0.0.0-20240123012728-ef4313101c80
+	google.golang.org/protobuf v1.36.5
+)
+
+require google.golang.org/genproto v0.0.0-20240123012728-ef4313101c80 // indirect
+
+replace github.com/Layr-Labs/protocol-apis-annotations => ../protocol-apis-annotations

buf-plugin-openapi/go.sum

@@ -0,0 +1,10 @@
+github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/genproto v0.0.0-20240123012728-ef4313101c80 h1:KAeGQVN3M9nD0/bQXnr/ClcEMJ968gUXJQ9pwfSynuQ=
+google.golang.org/genproto v0.0.0-20240123012728-ef4313101c80/go.mod h1:cc8bqMqtv9gMOr0zHg2Vzff5ULhhL2IXP4sbcn32Dro=
+google.golang.org/genproto/googleapis/api v0.0.0-20240123012728-ef4313101c80 h1:Lj5rbfG876hIAYFjqiJnPHfhXbv+nzTWfm04Fg/XSVU=
+google.golang.org/genproto/googleapis/api v0.0.0-20240123012728-ef4313101c80/go.mod h1:4jWUdICTdgc3Ibxmr8nAJiiLHwQBY0UI0XZcEMaFKaA=
+google.golang.org/protobuf v1.36.5 h1:tPhr+woSbjfYvY6/GPufUoYizxw1cF/yFoxJ2fmpwlM=
+google.golang.org/protobuf v1.36.5/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=