protoc-gen-swagger

0.1.0 verified Fri May 01 auth: no python

A Python protoc plugin that generates Swagger/OpenAPI specifications from annotated protobuf files. Currently at version 0.1.0, released as a minimal early release. No regular release cadence established yet.

pip install protoc-gen-swagger

Common errors

error protoc-gen-swagger: command not found ↓

cause The plugin executable is not in PATH after pip install.

fix

Ensure the Python Scripts directory (e.g., ~/.local/bin on Linux) is in your PATH. Or run: python -m protoc_gen_swagger

error protoc: error: Unknown flag: --swagger_out ↓

cause protoc does not see the plugin, likely because protoc-gen-swagger is not installed or not in PATH.

fix

Verify protoc-gen-swagger is installed and in PATH (type 'which protoc-gen-swagger'). Reinstall if needed.

Warnings

gotcha The plugin is very early (0.1.0). It may not support all protobuf features and can generate incomplete or incorrect swagger specs. Test thoroughly. ↓

fix Validate output swagger.json against your schema expectations.

gotcha protoc-gen-swagger depends on protoc being installed and the plugin being in your PATH. Missing protoc leads to cryptic errors like 'protoc: command not found'. ↓

fix Install protoc from https://github.com/protocolbuffers/protobuf/releases.

Imports

protoc_gen_swagger
```
import protoc_gen_swagger
```
Direct import of the module works if you need to invoke the plugin programmatically.

Quickstart

Invoke protoc with the swagger plugin (requires protoc-gen-swagger installed and in PATH).

# Generate swagger.json from a .proto file using the protoc plugin
# Make sure you have protoc installed, then run:
# protoc --swagger_out=. --proto_path=protos protos/your_service.proto

import subprocess
import os

proto_file = "your_service.proto"
proto_path = "protos"
output_dir = "."

cmd = [
    "protoc",
    f"--swagger_out={output_dir}",
    f"--proto_path={proto_path}",
    proto_file
]
subprocess.run(cmd, check=True)
print("Generated swagger.json")