{"id":3747,"library":"protoc-gen-openapiv2","title":"protoc-gen-openapiv2 Python Wrapper","description":"This Python package provides a convenient wrapper to install the `protoc-gen-openapiv2` binary. The binary generates OpenAPI v2 (Swagger) definitions directly from Protocol Buffer service definitions, making it a critical component for gRPC Gateway projects to expose gRPC services as RESTful APIs. It is currently at version 0.0.1, with development closely tied to the upstream Go project.","status":"active","version":"0.0.1","language":"en","source_language":"en","source_url":"https://github.com/unionai-oss/protoc-gen-openapiv2","tags":["protobuf","grpc","openapi","swagger","api-generation","grpc-gateway","protoc-plugin"],"install":[{"cmd":"pip install protoc-gen-openapiv2","lang":"bash","label":"Install protoc-gen-openapiv2"}],"dependencies":[],"imports":[],"quickstart":{"code":"import subprocess\nimport os\nimport sys\n\n# --- Prerequisites Check --- \n# This library's core function is a 'protoc' plugin, so 'protoc' and the plugin\n# binary must be available in your system's PATH.\n\ndef check_command(cmd_name):\n    return subprocess.run([\"which\", cmd_name], capture_output=True).returncode == 0\n\nif not check_command(\"protoc\"):\n    print(\"Error: 'protoc' (Protocol Buffer compiler) not found in PATH.\", file=sys.stderr)\n    print(\"Please install protoc. E.g., on Debian/Ubuntu: 'sudo apt install protobuf-compiler'\", file=sys.stderr)\n    sys.exit(1)\n\nif not check_command(\"protoc-gen-openapiv2\"):\n    print(\"Error: 'protoc-gen-openapiv2' not found in PATH.\", file=sys.stderr)\n    print(\"This Python package installs the binary, but you may need to add its install location (e.g., ~/.local/bin) to your PATH.\", file=sys.stderr)\n    sys.exit(1)\n\n# --- 1. Create a dummy .proto file for demonstration ---\nproto_file = \"example.proto\"\noutput_dir = \"./openapi_output\"\nswagger_output_file = os.path.join(output_dir, \"example.swagger.json\")\n\nproto_content = \"\"\"\nsyntax = \"proto3\";\npackage example;\nimport \"google/api/annotations.proto\"; // Essential for gRPC Gateway HTTP annotations\n\nservice MyService {\n  rpc MyMethod (MyRequest) returns (MyResponse) {\n    option (google.api.http) = {\n      get: \"/v1/example/{query}\"\n    };\n  }\n}\nmessage MyRequest {\n  string query = 1;\n}\nmessage MyResponse {\n  string result = 1;\n}\n\"\"\"\nwith open(proto_file, \"w\") as f:\n    f.write(proto_content)\n\nos.makedirs(output_dir, exist_ok=True)\n\n# --- 2. Run protoc with the openapiv2 plugin ---\n# The 'google/api/annotations.proto' needs to be discoverable by protoc.\n# It's typically found in your protoc installation or the grpc-gateway repo.\n# If not, you might need to add: -I/path/to/grpc-gateway/third_party/googleapis\nprotoc_command = [\n    \"protoc\",\n    \"-I.\", # Look for proto files in the current directory\n    f\"--openapiv2_out={output_dir}\", # Output directory for OpenAPI spec\n    \"--openapiv2_opt=logtostderr=true\", # Optional: log to stderr for debugging\n    proto_file\n]\n\nprint(f\"Executing command: {' '.join(protoc_command)}\\n\")\n\ntry:\n    result = subprocess.run(protoc_command, check=True, capture_output=True, text=True)\n    print(\"STDOUT:\\n\", result.stdout)\n    if result.stderr:\n        print(\"STDERR:\\n\", result.stderr) # Often contains warnings or logs from the plugin\n    print(f\"\\nSuccessfully generated OpenAPI v2 spec at: {swagger_output_file}\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error generating OpenAPI spec: {e}\", file=sys.stderr)\n    print(f\"Command: {' '.join(e.cmd)}\", file=sys.stderr)\n    print(f\"STDOUT:\\n{e.stdout}\", file=sys.stderr)\n    print(f\"STDERR:\\n{e.stderr}\", file=sys.stderr)\n    sys.exit(1)\nexcept FileNotFoundError as e:\n    print(f\"Error: Command not found. {e}\", file=sys.stderr)\n    sys.exit(1)\nfinally:\n    # --- Clean up --- \n    if os.path.exists(proto_file):\n        os.remove(proto_file)\n    print(f\"\\nCleaned up temporary '{proto_file}'. The output spec remains in '{output_dir}'.\")","lang":"python","description":"This quickstart demonstrates how to use the `protoc-gen-openapiv2` plugin via a Python script. It creates a dummy `.proto` file, then executes the `protoc` command to generate an OpenAPI v2 specification. This highlights that the package primarily provides a command-line tool, not Python symbols for direct import. Ensure `protoc` is installed and `protoc-gen-openapiv2` is in your system's PATH."},"warnings":[{"fix":"Always interact with `protoc-gen-openapiv2` through the `protoc` command-line tool, typically within a build script or Makefile. Do not expect to `import protoc_gen_openapiv2` in your Python application code.","message":"The `protoc-gen-openapiv2` Python package primarily installs a command-line binary. Its core functionality is invoked via the `protoc` command, not by importing Python modules and calling functions directly.","severity":"gotcha","affected_versions":"0.0.1"},{"fix":"Install `protoc` separately. For example, on Debian/Ubuntu: `sudo apt install protobuf-compiler`. For other systems, refer to the official Protocol Buffers documentation.","message":"The `protoc` (Protocol Buffer compiler) binary must be installed on your system and accessible in your system's PATH for this plugin to function. This Python package only installs the OpenAPI v2 generator plugin, not `protoc` itself.","severity":"gotcha","affected_versions":"0.0.1"},{"fix":"Ensure the directory where `pip` installs binaries is included in your system's PATH environment variable. Alternatively, call the binary using its full path.","message":"After installing `protoc-gen-openapiv2` via `pip`, the `protoc-gen-openapiv2` binary might be installed into a user-specific directory (e.g., `~/.local/bin` in Linux or `AppData\\Roaming\\Python\\Scripts` in Windows for Python >= 3.3). This directory might not be in your system's PATH by default.","severity":"gotcha","affected_versions":"0.0.1"},{"fix":"Verify that all directories containing `.proto` files are correctly added to the `protoc` command with `-I` flags. For `google/api/annotations.proto`, you might need to clone the `grpc-ecosystem/grpc-gateway` repository and include its `third_party/googleapis` directory.","message":"When using `protoc`, correctly specifying include paths (`-I` flags) for all `.proto` files, especially imported ones like `google/api/annotations.proto` (common for gRPC Gateway), is critical. Incorrect paths will lead to `File not found` errors during generation.","severity":"gotcha","affected_versions":"0.0.1"},{"fix":"Pin your `protoc-gen-openapiv2` version in your `requirements.txt` or build environment to avoid unexpected breakage. Thoroughly test when upgrading to new versions.","message":"Given its early version `0.0.1`, future updates (even minor releases) are likely to introduce breaking changes to command-line options, generated output, or dependencies without strictly adhering to semantic versioning guidelines.","severity":"breaking","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}