{"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.","language":"python","status":"active","last_verified":"Sat Apr 11","install":{"commands":["pip install protoc-gen-openapiv2"],"cli":{"name":"protoc-gen-openapiv2","version":"sh: 1: protoc-gen-openapiv2: not found"}},"imports":[],"auth":{"required":false,"env_vars":[]},"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.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}