{"id":19216442,"url":"https://github.com/ogen-go/protoc-gen-oas","last_synced_at":"2025-08-04T18:05:55.159Z","repository":{"id":159311810,"uuid":"634493251","full_name":"ogen-go/protoc-gen-oas","owner":"ogen-go","description":"Generate OpenAPI v3 from protobuf","archived":false,"fork":false,"pushed_at":"2025-07-23T07:19:33.000Z","size":489,"stargazers_count":25,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-31T19:26:50.059Z","etag":null,"topics":["go","openapi","protobuf"],"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/ogen-go.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-04-30T09:59:54.000Z","updated_at":"2025-07-23T07:19:30.000Z","dependencies_parsed_at":"2023-10-03T12:09:28.266Z","dependency_job_id":"d5c0c471-a766-4c03-8983-9556b6d31841","html_url":"https://github.com/ogen-go/protoc-gen-oas","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/ogen-go/protoc-gen-oas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogen-go%2Fprotoc-gen-oas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogen-go%2Fprotoc-gen-oas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogen-go%2Fprotoc-gen-oas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogen-go%2Fprotoc-gen-oas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ogen-go","download_url":"https://codeload.github.com/ogen-go/protoc-gen-oas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ogen-go%2Fprotoc-gen-oas/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268738989,"owners_count":24299558,"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-04T02:00:09.867Z","response_time":79,"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","openapi","protobuf"],"created_at":"2024-11-09T14:17:01.981Z","updated_at":"2025-08-04T18:05:55.064Z","avatar_url":"https://github.com/ogen-go.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# protoc-gen-oas [![Go Reference](https://img.shields.io/badge/go-pkg-00ADD8)](https://pkg.go.dev/github.com/ogen-go/protoc-gen-oas#section-documentation) [![codecov](https://img.shields.io/codecov/c/github/ogen-go/protoc-gen-oas?label=cover)](https://codecov.io/gh/ogen-go/protoc-gen-oas) [![experimental](https://img.shields.io/badge/-experimental-blueviolet)](https://go-faster.org/docs/projects/status#experimental)\n\n`protoc-gen-oas` is protoc plugin for generate OpenAPI v3.x.x from proto files.\n\n# Install\n\n```shell\ngo install github.com/ogen-go/protoc-gen-oas/cmd/protoc-gen-oas@latest\n```\n\n# Usage\n\n```shell\nprotoc --oas_out=. service.proto\n```\n\n# Features\n\n- support [API annotations](https://github.com/googleapis/googleapis/blob/master/google/api/annotations.proto) in methods\n- support [field behavior](https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto) in message field description\n- support [field info](https://github.com/googleapis/googleapis/blob/master/google/api/field_info.proto) in message field description\n\n# Generate OpenAPI\n\n## Path param\n\n```protobuf title=\"service.proto\"\nsyntax = \"proto3\";\n\npackage service.v1;\n\nimport \"google/api/annotations.proto\";\n\noption go_package = \"service/v1;service\";\n\nservice Service {\n  rpc GetItem(GetItemRequest) returns (Item) {\n    option (google.api.http) = {\n      get: \"/api/v1/items/{id}\" // \u003c--\n    };\n  }\n}\n\nmessage GetItemRequest {\n  string id = 1; // \u003c--\n}\n\nmessage Item {\n  string id = 1;\n  string name = 2;\n}\n```\n\n```yaml title=\"openapi.yaml\"\nopenapi: 3.1.0\ninfo:\n  title: \"\"\n  version: \"\"\npaths:\n  /api/v1/items/{id}:\n    get:\n      operationId: getItem\n      parameters:\n        - name: id       # \u003c--\n          in: path       # \u003c--\n          required: true # \u003c--\n          schema:        # \u003c--\n            type: string # \u003c--\n      responses:\n        \"200\":\n          description: service.v1.Service.GetItem response\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Item'\ncomponents:\n  schemas:\n    Item:\n      type: object\n      properties:\n        id:\n          type: string\n        name:\n          type: string\n```\n\n## Query param\n\n```protobuf title=\"service.proto\"\nsyntax = \"proto3\";\n\npackage service.v1;\n\nimport \"google/api/annotations.proto\";\n\noption go_package = \"service/v1;service\";\n\nservice Service {\n  rpc GetItems(GetItemsRequest) returns (GetItemsResponse) {\n    option (google.api.http) = {\n      get: \"/api/v1/items\"\n    };\n  }\n}\n\nmessage GetItemsRequest {\n  int32 limit = 1;  // \u003c--\n  int32 offset = 2; // \u003c--\n}\n\nmessage GetItemsResponse {\n  repeated Item items = 1;\n  int32 total_count = 2;\n}\n\nmessage Item {\n  string id = 1;\n  string name = 2;\n}\n```\n\n```yaml title=\"openapi.yaml\"\nopenapi: 3.1.0\ninfo:\n  title: \"\"\n  version: \"\"\npaths:\n  /api/v1/items:\n    get:\n      operationId: getItems\n      parameters:\n        - name: limit     # \u003c--\n          in: query       # \u003c--\n          schema:         # \u003c--\n            type: integer # \u003c--\n            format: int32 # \u003c--\n        - name: offset    # \u003c--\n          in: query       # \u003c--\n          schema:         # \u003c--\n            type: integer # \u003c--\n            format: int32 # \u003c--\n      responses:\n        \"200\":\n          description: service.v1.Service.GetItems response\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/GetItemsResponse'\ncomponents:\n  schemas:\n    GetItemsResponse:\n      type: object\n      properties:\n        items:\n          type: array\n          items:\n            $ref: '#/components/schemas/Item'\n        totalCount:\n          type: integer\n          format: int32\n    Item:\n      type: object\n      properties:\n        id:\n          type: string\n        name:\n          type: string\n```\n\n## Mark field as required\n\n```protobuf title=\"service.proto\"\nsyntax = \"proto3\";\n\npackage service.v1;\n\nimport \"google/api/annotations.proto\";\nimport \"google/api/field_behavior.proto\";\n\noption go_package = \"service/v1;service\";\n\nservice Service {\n  rpc CreateItem(CreateItemRequest) returns (CreateItemResponse) {\n    option (google.api.http) = {\n      post: \"/api/v1/items\"\n      body: \"*\"\n    };\n  }\n}\n\nmessage CreateItemRequest {\n  string name = 1 [(google.api.field_behavior) = REQUIRED]; // \u003c--\n}\n\nmessage CreateItemResponse {\n  string id = 1 [(google.api.field_behavior) = REQUIRED]; // \u003c--\n}\n```\n\n```yaml title=\"openapi.yaml\"\nopenapi: 3.1.0\ninfo:\n  title: \"\"\n  version: \"\"\npaths:\n  /api/v1/items:\n    post:\n      operationId: createItem\n      requestBody:\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/CreateItemRequest'\n        required: true\n      responses:\n        \"200\":\n          description: service.v1.Service.CreateItem response\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/CreateItemResponse'\ncomponents:\n  schemas:\n    CreateItemRequest:\n      type: object\n      properties:\n        name:\n          type: string\n      required: # \u003c--\n        - name  # \u003c--\n    CreateItemResponse:\n      type: object\n      properties:\n        id:\n          type: string\n      required: # \u003c--\n        - id    # \u003c--\n```\n\n## Mark field as deprecated\n\n```protobuf title=\"service.proto\"\nsyntax = \"proto3\";\n\npackage service.v1;\n\nimport \"google/api/annotations.proto\";\n\noption go_package = \"service/v1;service\";\n\nservice Service {\n  rpc GetItems(GetItemsRequest) returns (GetItemsResponse) {\n    option (google.api.http) = {\n      get: \"/api/v1/items\"\n    };\n  }\n}\n\nmessage GetItemsRequest {\n  int32 limit = 1;\n  int32 offset = 2 [deprecated = true]; // \u003c--\n}\n\nmessage GetItemsResponse {\n  repeated Item items = 1;\n  int32 total_count = 2;\n}\n\nmessage Item {\n  string id = 1;\n  string name = 2 [deprecated = true]; // \u003c--\n}\n```\n\n```yaml title=\"openapi.yaml\"\nopenapi: 3.1.0\ninfo:\n  title: \"\"\n  version: \"\"\npaths:\n  /api/v1/items:\n    get:\n      operationId: getItems\n      parameters:\n        - name: limit\n          in: query\n          schema:\n            type: integer\n            format: int32\n        - name: offset       # \u003c--\n          in: query          # \u003c--\n          schema:            # \u003c--\n            type: integer    # \u003c--\n            format: int32    # \u003c--\n            deprecated: true # \u003c--\n      responses:\n        \"200\":\n          description: service.v1.Service.GetItems response\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/GetItemsResponse'\ncomponents:\n  schemas:\n    GetItemsResponse:\n      type: object\n      properties:\n        items:\n          type: array\n          items:\n            $ref: '#/components/schemas/Item'\n        totalCount:\n          type: integer\n          format: int32\n    Item:\n      type: object\n      properties:\n        id:\n          type: string\n        name:              # \u003c--\n          type: string     # \u003c--\n          deprecated: true # \u003c--\n```\n\n## Snake case\n\n```protobuf title=\"service.proto\"\nsyntax = \"proto3\";\n\npackage service.v1;\n\nimport \"google/api/annotations.proto\";\nimport \"google/protobuf/empty.proto\";\n\noption go_package = \"service/v1;service\";\n\nservice Service {\n  rpc DeleteItem(DeleteItemRequest) returns (google.protobuf.Empty) {\n    option (google.api.http) = {\n      delete: \"/api/v1/items/{item_id}\"\n      body: \"*\"\n    };\n  }\n}\n\nmessage DeleteItemRequest {\n  string item_id = 1 [json_name = \"item_id\"]; // \u003c--\n}\n```\n\n```yaml title=\"openapi.yaml\"\nopenapi: 3.1.0\ninfo:\n  title: \"\"\n  version: \"\"\npaths:\n  /api/v1/items/{item_id}:\n    delete:\n      operationId: deleteItem\n      parameters:\n        - name: item_id  # \u003c--\n          in: path       # \u003c--\n          required: true # \u003c--\n          schema:        # \u003c--\n            type: string # \u003c--\n      responses:\n        \"200\":\n          description: service.v1.Service.DeleteItem response\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Empty'\ncomponents:\n  schemas:\n    Empty:\n      type: object\n```\n\n## Set field format\n\n```protobuf title=\"service.proto\"\nsyntax = \"proto3\";\n\npackage service.v1;\n\nimport \"google/api/annotations.proto\";\nimport \"google/api/field_info.proto\";\n\noption go_package = \"service/v1;service\";\n\nservice Service {\n  rpc GetItem(GetItemRequest) returns (Item) {\n    option (google.api.http) = {\n      get: \"/api/v1/items/{id}\"\n    };\n  }\n}\n\nmessage GetItemRequest {\n  string id = 1 [(google.api.field_info).format = UUID4]; // \u003c--\n}\n\nmessage Item {\n  string id = 1 [(google.api.field_info).format = UUID4]; // \u003c--\n  string name = 2;\n}\n```\n\n```yaml title=\"openapi.yaml\"\nopenapi: 3.1.0\ninfo:\n  title: \"\"\n  version: \"\"\npaths:\n  /api/v1/items/{id}:\n    get:\n      operationId: getItem\n      parameters:\n        - name: id\n          in: path\n          required: true\n          schema:\n            type: string\n            format: uuid # \u003c--\n      responses:\n        \"200\":\n          description: service.v1.Service.GetItem response\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Item'\ncomponents:\n  schemas:\n    Item:\n      type: object\n      properties:\n        id:\n          type: string\n          format: uuid # \u003c--\n        name:\n          type: string\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogen-go%2Fprotoc-gen-oas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fogen-go%2Fprotoc-gen-oas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fogen-go%2Fprotoc-gen-oas/lists"}