{"id":34176329,"url":"https://github.com/kollalabs/protoc-gen-openapi","last_synced_at":"2026-03-12T19:34:54.976Z","repository":{"id":40477999,"uuid":"436435410","full_name":"kollalabs/protoc-gen-openapi","owner":"kollalabs","description":"Generate OpenAPI v3 spec from protocol buffer gRPC service","archived":false,"fork":false,"pushed_at":"2025-12-12T20:02:53.000Z","size":6614,"stargazers_count":51,"open_issues_count":6,"forks_count":8,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-18T10:17:51.261Z","etag":null,"topics":["openapi","protocol-buffers"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kollalabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-12-09T00:37:28.000Z","updated_at":"2025-11-07T20:52:58.000Z","dependencies_parsed_at":"2024-04-25T19:30:38.964Z","dependency_job_id":"f06b62c1-9a10-4ef4-b7a6-98bbef3b77d3","html_url":"https://github.com/kollalabs/protoc-gen-openapi","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/kollalabs/protoc-gen-openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kollalabs%2Fprotoc-gen-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kollalabs%2Fprotoc-gen-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kollalabs%2Fprotoc-gen-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kollalabs%2Fprotoc-gen-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kollalabs","download_url":"https://codeload.github.com/kollalabs/protoc-gen-openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kollalabs%2Fprotoc-gen-openapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30439986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T14:34:45.044Z","status":"ssl_error","status_checked_at":"2026-03-12T14:09:33.793Z","response_time":114,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["openapi","protocol-buffers"],"created_at":"2025-12-15T12:31:35.305Z","updated_at":"2026-03-12T19:34:54.955Z","avatar_url":"https://github.com/kollalabs.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# protoc-gen-openapi\n\nContains a protoc plugin that generates openapi v3 documents\n\n**Forked from [github.com/google/gnostic/cmd/protoc-gen-openapi](https://github.com/google/gnostic/tree/main/cmd/protoc-gen-openapi)**\n\nInstallation:\n\n    go install github.com/kollalabs/protoc-gen-openapi@latest\n\nUsage:\n\n    protoc sample.proto -I. --openapi_out=version=1.2.3:.\n\n## Testing\n\nTo see output during tests use `log.Print*`\n\n```\ngo clean -testcache \u0026\u0026 go test\n```\n\n## Added Features\nWe have added some features that the Gnostic team most likely doesn't want to add :-)\nSome are fairly Kolla specific, sorry. We try to hide Kolla specific functionality\nin a way that won't trip anyone up.\n\n* [Better Enum Support](#better-enum-support)\n* [Summary Field](#summary-field)\n* [Validation (protoc-gen-validate)](#validation)\n* [Google Field Behavior Annotations](#google-field-behavior-annotations)\n* [OAS3 header support](#oas3-header-support)\n\n### Better Enum Support\nEnums work better by using string values of proto enums instead of ints.\n\n### Summary Field\n\nSometimes you want more control over certain properties in the OpenAPI manifest. In our\ncase we wanted to use the `summary` property on routes to look nice for generating\ndocumentation from the OpenAPI manifest. Normally the summary comes simply from the\nname of the route. We added a feature that parses the comment over the proto service\nmethod and looks for a pipe character (\"`|`\") and if it sees it, it will take anything to\nthe left of it and put it in the `summary` field, and anything to the right of it will\nbe the `description`. If no pipe is found it puts the whole comment in the description\nlike normal. From `/examples/tests/summary/message.proto`:\n\n```proto\nservice Messaging {\n    // Update Message Summary | This function updates a message.\n    rpc UpdateMessage(Message) returns(Message) {\n        option(google.api.http) = {\n            patch: \"/v1/messages/{message_id}\"\n            body: \"text\"\n        };\n    }\n}\n```\n\nIt generates the following OpenAPI:\n\n```yaml\n#...\npaths:\n    /v1/messages/{message_id}:\n        patch:\n            tags:\n                - Messaging\n            summary: Update Message Summary # Look at this beautiful summary...\n            description: This function updates a message.\n#...\n```\n\n### Validation\n\nWe added partial support for `protoc-gen-validate` annotations\n\nOpenAPI spec allows for a small handful of input validation configurations.\nProto has an awesome plugin called `protoc-gen-validate` for generating validation code in\nGo, Java, C++, etc. We took those same annotations and added support in this project\nfor them.\n\nUsage: add `validate=true` to protoc command.\n\n`protoc sample.proto -I. --openapi_out=version=1.2.3,validate=true:.`\n\n#### Example\n\n```proto\nmessage Message {\n    string message_id = 1;\n    string text = 2 [(validate.rules)= {\n        string: {\n            uri:true,\n            max_len:45,\n            min_len:1\n        }\n    }];\n    int64 mynum = 3 [(validate.rules).int64 = {gte:1, lte:30}];\n}\n\n```\n\noutputs:\n\n```yaml\ncomponents:\n    schemas:\n        Message:\n            properties:\n                message_id:\n                    type: string\n                text:\n                    maxLength: 45\n                    minLength: 1\n                    type: string\n                    format: uri\n                mynum:\n                    maximum: !!float 30\n                    minimum: !!float 1\n                    type: integer\n                    format: int64\n\n```\n\n#### Supported Validators\n\nString\n- uri\n- uuid\n- email\n- ipv4\n- ipv6\n- max_len\n- min_len\n\nInt32\n- gte\n- lte\n\nInt64\n- gte\n- lte\n\nAdding more can easily be done in the function `addValidationRules` in `/generator/openapi-v3.yaml`\n\n### Google Field Behavior Annotations\n\n* `(google.api.field_behavior) = REQUIRED` will add the field to the required list in the openAPI schema\n* `(google.api.field_behavior) = OUTPUT_ONLY` will add the `readOnly` property to the field\n* `(google.api.field_behavior) = INPUT_ONLY` will add the `writeOnly` property to the field\n* TODO: `(google.api.field_behavior) = IMMUTABLE` will add the `x-createOnly` property to the field (not supported by openapi yet)\n\n### OAS3 header support\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkollalabs%2Fprotoc-gen-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkollalabs%2Fprotoc-gen-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkollalabs%2Fprotoc-gen-openapi/lists"}