{"id":22428240,"url":"https://github.com/technicallyjosh/protoc-gen-openapi","last_synced_at":"2026-02-28T22:14:02.774Z","repository":{"id":65051760,"uuid":"580132646","full_name":"technicallyjosh/protoc-gen-openapi","owner":"technicallyjosh","description":"OpenAPI generation from Protobuf","archived":false,"fork":false,"pushed_at":"2025-07-11T01:54:30.000Z","size":152,"stargazers_count":8,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-13T05:41:19.494Z","etag":null,"topics":["go","openapi3","protobuf","rpc"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/technicallyjosh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-12-19T19:57:16.000Z","updated_at":"2025-04-11T06:03:58.000Z","dependencies_parsed_at":"2024-04-30T20:40:09.255Z","dependency_job_id":"6f0f7227-4406-4f6c-bf5e-1893efb3060f","html_url":"https://github.com/technicallyjosh/protoc-gen-openapi","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/technicallyjosh/protoc-gen-openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicallyjosh%2Fprotoc-gen-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicallyjosh%2Fprotoc-gen-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicallyjosh%2Fprotoc-gen-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicallyjosh%2Fprotoc-gen-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/technicallyjosh","download_url":"https://codeload.github.com/technicallyjosh/protoc-gen-openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicallyjosh%2Fprotoc-gen-openapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271128754,"owners_count":24703879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-19T02:00:09.176Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","openapi3","protobuf","rpc"],"created_at":"2024-12-05T20:14:12.690Z","updated_at":"2025-08-19T09:11:33.644Z","avatar_url":"https://github.com/technicallyjosh.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# protoc-gen-openapi\n\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/technicallyjosh/protoc-gen-openapi?style=flat-square)\n[![lint status](https://img.shields.io/github/actions/workflow/status/technicallyjosh/protoc-gen-openapi/run-lint.yaml?style=flat-square\u0026label=lint)](https://github.com/technicallyjosh/protoc-gen-openapi/actions/workflows/run-lint.yaml)\n[![go report card](https://goreportcard.com/badge/github.com/technicallyjosh/protoc-gen-openapi?style=flat-square)](https://goreportcard.com/report/github.com/technicallyjosh/protoc-gen-openapi)\n\n**Yes**, this is _another_ protoc generator for OpenAPI. I created this for a\ncouple\nreasons...\n\n- I wanted to learn protoc generation with a real-world problem.\n- The official google one sticks to gRPC and envoy standards. My team and I use\n  Twirp and other REST frameworks. _Sometimes you just want to define models and\n  an API for docs._\n- Others try to do too much per the spec and fail to do the most common things\n  well.\n\n_**DISCLAIMER: This will be a limited subset of the OAPI3 specification. Not\neverything will make it in here. Why? Read the last bullet point above. :)**_\n\n_Some patterns were heavily inspired\nby [gnostic](https://github.com/google/gnostic)._\n\n## Installation\n\n```terminal\ngo install github.com/technicallyjosh/protoc-gen-openapi@latest\n```\n\n## Options\n\n| Option             | Description                                                                       | Default          |\n|--------------------|-----------------------------------------------------------------------------------|------------------|\n| `version`          | The version of the API.                                                           | 0.0.1            |\n| `title`            | The title of the API.                                                             |                  |\n| `description`      | A description of the API.                                                         |                  |\n| `include`          | A list of proto package names to include only. `ignore` is ran after this         |                  |\n| `ignore`           | A list of proto package names to ignore delimited by pipes.                       |                  |\n| `default_response` | The default response to be used.\u003csup\u003e1\u003c/sup\u003e                                      |                  |\n| `content_type`     | The content type to be associated with all operations.\u003csup\u003e1\u003c/sup\u003e                | application/json |\n| `json_names`       | Use the JSON names that Protobuf provides. Otherwise, proto field names are used. | false            |\n| `json_out`         | Create a JSON file instead of the default YAML.                                   | false            |\n| `host`             | The host to be used for all operations.\u003csup\u003e1\u003c/sup\u003e                               |                  |\n| `filename`         | Specify the filename to output.                                                   | openapi.yaml     |\n\n\u003csup\u003e1\u003c/sup\u003e _Can be overridden on a file, service, or method._\n\n## Build Examples\n\nBelow are some basic examples on how to use this generator.\n\n### Protoc\n\n```bash\nprotoc \\\n  --openapi_out=. \\\n  --openapi_opt=version=1.0.0 \\\n  --openapi_opt=title=\"My Awesome API\" \\\n  api/some_service.proto\n```\n\n### Buf\n\n**buf.yaml**\n\n```yaml\n# ... other things\ndeps:\n  - buf.build/technicallyjosh/protoc-gen-openapi\n```\n\n**buf.gen.yaml**\n\n```yaml\nplugins:\n  - name: go\n    out: api\n    opt:\n      - paths=source_relative\n  - name: openapi\n    strategy: all # important so all files are ran in the same generation.\n    out: api\n    opt:\n      - title=My Awesome API\n      - description=Look how awesome my API is!\n      - ignore=module.v1|module.v2\n      - default_response=SomeErrorObject\n```\n\n## Basic Usage Example\n\n```protobuf\nsyntax = \"proto3\";\n\nimport \"oapi/v1/field.proto\";\nimport \"oapi/v1/file.proto\";\nimport \"oapi/v1/method.proto\";\nimport \"oapi/v1/service.proto\";\n\noption (oapi.v1.file) = {\n  servers {\n    url: \"myawesomeapi.com\"\n  }\n\n  security_schemes: {\n    name: \"bearer_auth\"\n    scheme: {\n      type: \"http\"\n      scheme: \"bearer\"\n      bearer_format: \"JWT\"\n    }\n  }\n\n  // Since this is at the file level, it's applied to all.\n  security: {\n    name: \"bearer_auth\"\n    scopes: [\"read:resource\"]\n  }\n};\n\nservice MyService {\n  option (oapi.v1.service) = {\n    prefix: \"/v1\"\n    x_display_name: \"My Service\"\n  };\n\n  rpc CreateSomething (CreateSomethingRequest) returns (CreateSomethingResponse) {\n    option (oapi.v1.method) = {\n      post: \"create-something\"\n      summary: \"Create Something\"\n      status: 201\n    };\n  }\n}\n\nmessage CreateSomethingRequest {\n  // The name of something.\n  // Example: something-awesome\n  string name = 1 [(oapi.v1.required) = true];\n}\n\nmessage CreateSomethingResponse {\n  // The ID of something.\n  string id = 1;\n  string name = 2;\n}\n```\n\n## Features\n\n\u003e **Note**\n\u003e\n\u003e Defining features is a work in progress. I aim to explain all that's possible\n\u003e the best I can.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3\u003eServer definitions\u003c/h3\u003e\u003c/summary\u003e\n\nYou can define servers at the file, service, or method level. Each one overrides\nthe previous. This allows for more advanced composition.\n\n**Example:**\n\n```protobuf\nsyntax = \"proto3\";\n\nimport \"google/protobuf/empty.proto\";\nimport \"oapi/v1/file.proto\";\nimport \"oapi/v1/method.proto\";\nimport \"oapi/v1/service.proto\";\n\n\noption (oapi.v1.file) = {\n  servers {\n    url: \"myawesomeapi.com\" // file-defined for all services and methods\n  }\n};\n\nservice MyService {\n  option (oapi.v1.service) = {\n    servers {\n      url: \"myawesomeapi2.com\" // overrides file-defined\n    }\n  };\n\n  rpc CreateSomething (google.protobuf.Empty) returns (google.protobuf.Empty) {\n    option (oapi.v1.method) = {\n      servers {\n        url: \"myaweseomeapi3.com\" // overrides service-defined\n      }\n    };\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3\u003eService Prefixes\u003c/h3\u003e\u003c/summary\u003e\n\nEach service can have a path prefix set for all methods to inherit. This is\nuseful when versioning your API or if you have a parameter that is defined for\neach method route.\n\n_**You can override the entire path in the method by starting the path out with\na `/`.**_\n\n**Example:**\n\n```protobuf\nsyntax = \"proto3\";\n\nimport \"google/protobuf/empty.proto\";\nimport \"oapi/v1/file.proto\";\nimport \"oapi/v1/method.proto\";\nimport \"oapi/v1/service.proto\";\n\noption (oapi.v1.file) = {\n  servers {\n    url: \"myawesomeapi.com\"\n  }\n};\n\nservice MyService {\n  option (oapi.v1.service) = {\n    prefix: \"/v1\"\n  };\n\n  rpc CreateSomething (google.protobuf.Empty) returns (google.protobuf.Empty) {\n    option (oapi.v1.method) = {\n      post: \"create\" // becomes /v1/create\n    };\n  }\n\n  rpc OverrideSomething (google.protobuf.Empty) returns (google.protobuf.Empty) {\n    option (oapi.v1.method) = {\n      get: \"/create\" // becomes /create\n    };\n  }\n}\n```\n\n\u003c/details\u003e\n\n## Features In Progress\n\n- [Enum](https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values)\n  requirements on fields\n\n## Contributing\n\nComing... Right now I prefer that it's just me until I get a solid hold on\ngenerator patterns and the package is stable. I'm fully open to any suggestions\nthough!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnicallyjosh%2Fprotoc-gen-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechnicallyjosh%2Fprotoc-gen-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnicallyjosh%2Fprotoc-gen-openapi/lists"}