protoc-gen-connect-openapi is a Protobuf compiler plugin that generates OpenAPI specifications matching the Connect RPC interface.
Installation
Run directly
nix run github:spotdemo4/nur#protoc-gen-connect-openapi
Add to flake
devShells.default = pkgs.mkShell {
packages = with pkgs.trev; [
protoc-gen-connect-openapi
protobuf
];
};
Usage
Generate OpenAPI spec
Generate an OpenAPI specification from your proto files:
protoc --connect-openapi_out=. \
--connect-openapi_opt=base_url=https://api.example.com \
api/v1/*.proto
Specify output file
protoc --connect-openapi_out=. \
--connect-openapi_opt=output=openapi.yaml \
api/v1/*.proto
Multiple services
Generate separate specs for each service:
protoc --connect-openapi_out=. \
--connect-openapi_opt=separate_services=true \
api/v1/*.proto
Configuration options
Customize the generated OpenAPI spec:
The base URL for your API (e.g., https://api.example.com)
Output file name (default: openapi.yaml)
Output format: yaml or json (default: yaml)
API title in the OpenAPI spec
API version in the OpenAPI spec
Generate separate files for each service (default: false)
Example
Given a Connect RPC service:
syntax = "proto3";
package users.v1;
service UserService {
rpc GetUser(GetUserRequest) returns (GetUserResponse) {}
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) {}
}
message GetUserRequest {
string user_id = 1;
}
message GetUserResponse {
string user_id = 1;
string name = 2;
string email = 3;
}
protoc --connect-openapi_out=. \
--connect-openapi_opt=base_url=https://api.example.com \
--connect-openapi_opt=title="User API" \
--connect-openapi_opt=version=v1 \
api/v1/users.proto
openapi.yaml with Connect RPC HTTP endpoints:
openapi: 3.0.0
info:
title: User API
version: v1
servers:
- url: https://api.example.com
paths:
/users.v1.UserService/GetUser:
post:
operationId: users.v1.UserService.GetUser
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/users.v1.GetUserRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/users.v1.GetUserResponse'
Build automation
Integrate into your Nix build:
stdenv.mkDerivation {
name = "api-docs";
src = ./proto;
nativeBuildInputs = with pkgs.trev; [
protobuf
protoc-gen-connect-openapi
];
buildPhase = ''
protoc --connect-openapi_out=$out \
--connect-openapi_opt=base_url=https://api.example.com \
api/v1/*.proto
'';
}
Combine with API documentation tools like Redoc or Swagger UI to generate interactive API documentation from the OpenAPI spec.
Links
