{"id":13741815,"url":"https://github.com/NYTimes/openapi2proto","last_synced_at":"2025-05-08T22:32:30.701Z","repository":{"id":39833916,"uuid":"57053358","full_name":"nytimes/openapi2proto","owner":"nytimes","description":"A tool for generating Protobuf v3 schemas and gRPC service definitions from OpenAPI specifications","archived":false,"fork":false,"pushed_at":"2023-05-21T04:46:31.000Z","size":692,"stargazers_count":961,"open_issues_count":22,"forks_count":98,"subscribers_count":50,"default_branch":"master","last_synced_at":"2024-11-07T09:42:59.941Z","etag":null,"topics":[],"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/nytimes.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}},"created_at":"2016-04-25T15:30:02.000Z","updated_at":"2024-10-31T13:22:59.000Z","dependencies_parsed_at":"2024-01-24T21:02:33.484Z","dependency_job_id":"9226b9fa-0ab7-40f8-8c03-7acd8c6a2d43","html_url":"https://github.com/nytimes/openapi2proto","commit_stats":{"total_commits":221,"total_committers":22,"mean_commits":"10.045454545454545","dds":0.5927601809954751,"last_synced_commit":"965721280dc74049c84dea3f7566702d42a986e0"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nytimes%2Fopenapi2proto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nytimes%2Fopenapi2proto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nytimes%2Fopenapi2proto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nytimes%2Fopenapi2proto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nytimes","download_url":"https://codeload.github.com/nytimes/openapi2proto/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224782060,"owners_count":17369079,"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","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":[],"created_at":"2024-08-03T04:01:02.918Z","updated_at":"2024-11-15T12:31:19.423Z","avatar_url":"https://github.com/nytimes.png","language":"Go","readme":"# openapi2proto [![Build Status](https://travis-ci.org/nytimes/openapi2proto.svg?branch=master)](https://travis-ci.org/nytimes/openapi2proto)\n\nThis tool will accept an OpenAPI/Swagger definition (yaml or JSON) and generate a Protobuf v3 schema and gRPC service definition from it.\n\n## Install\n\nTo install, have Go installed with `$GOPATH/bin` on your `$PATH` and then:\n```\ngo install github.com/NYTimes/openapi2proto/cmd/openapi2proto@latest\n```\n\nOn Older versions of Go (\u003c1.15), use:\n```\ngo get -u github.com/NYTimes/openapi2proto/cmd/openapi2proto\n```\n\n## Run\n\nThere are some CLI flags for using the tool:\n* `-spec` to point to the appropriate OpenAPI spec file\n* `-annotate` to include (google.api.http options) for [grpc-gateway](https://github.com/gengo/grpc-gateway) users. This is disabled by default.\n* `-out` to have the output written to a file rather than `Stdout`. Defaults to `Stdout` if this is not specified.\n* `-indent` to override the default indentation for Protobuf specs of 4 spaces.\n* `-skip-rpcs` to skip generation of rpcs. These are generated by default.\n* `-skip-deprecated-rpcs` to skip generation of rpcs for endpoints marked as deprecated. This is disabled by default.\n* `-namespace-enums` to enable inserting the enum name as an enum prefix for each value. This is disabled by default.\n* `-add-autogenerated-comment` to add comment on top of the generated protos that those files are autogenerated and should not be modified. This is disabled by default.\n\n## Protobuf Tags\n* To allow for more control over how your protobuf schema evolves, all parameters and property definitions will accept an optional extension parameter, `x-proto-tag`, that will overide the generated tag with the value supplied.\n\n## External Files\n* Any externally referenced Open API spec will be fetched and inlined.\n* Any externally referenced Protobuf files will be added as imports.\n  * Example usage: `$ref: \"google/protobuf/timestamp.proto#/google.protobuf.Timestamp\"`\n\n## Global Options\n\nProtocol Buffer options such as package names are supported via `x-global-options` key.\n\n```yaml\nx-global-options:\n  go_package: myawesomepackage\n```\n\nWill generate:\n\n```protobuf\noption go_package = \"myawesomepackage\"\n```\n\n## Extensions\n\nGlobal extensions may be generated by specifying `x-extensions` key.\n\n```yaml\nx-extensions:\n- base: google.protobuf.MethodOptions\n  fields:\n  - name: role\n    type: string\n    number: 50001\n  - name: visibility\n    type: string\n    number: 50002\n  - name: timeout\n    type: int32\n    number: 50003\n```\n\nWill generate:\n\n```protobuf\nextend google.protobuf.MethodOptions {\n    string role = 50001;\n    string visibility = 50002;\n    int32 timeout = 50003;\n}\n```\n\nNested extensions are currently not supported.\n\n## Method Options\n\nMethod options may be generated by specifying the `x-options` key within each method.\n\n```yaml\npaths:\n  /foo\n    post:\n      x-options:\n        bar: baz\n```\n\nWill generate:\n\n```protobuf\n    rpc foo(...) returns (...) {\n      option (bar) = \"baz\";\n    }\n```\n\n## Caveats\n\n* Fields with scalar types that can also be \"null\" will get wrapped with one of the `google.protobuf.*Value` types.\n* Fields with that have more than 1 type and the second type is not \"null\" will be replaced with the `google.protobuf.Any` type.\n* Endpoints that respond with an array will be wrapped with a message type that has a single field, 'items', that contains the array.\n* Only \"200\" and \"201\" responses are inspected for determining the expected return value for RPC endpoints.\n* To prevent enum collisions and to match the [protobuf style guide](https://developers.google.com/protocol-buffers/docs/style#enums), enum values will be `CAPITALS_WITH_UNDERSCORES` and nested enum values will have their parent types prepended to their names.\n\n\n## Example\n\n```\n╰─➤  openapi2proto -spec swagger.yaml -annotate\nsyntax = \"proto3\";\n\npackage swaggerpetstore;\n\nimport \"google/api/annotations.proto\";\nimport \"google/protobuf/empty.proto\";\n\nmessage AddPetRequest {\n    message PetMessage {\n        int64 id = 1;\n        string name = 2;\n        string tag = 3;\n    }\n\n    // Pet to add to the store\n    PetMessage pet = 1;\n}\n\nmessage AddPetResponse {\n    int64 id = 1;\n    string name = 2;\n    string tag = 3;\n}\n\nmessage DeletePetRequest {\n    // ID of pet to delete\n    int64 id = 1;\n}\n\nmessage FindPetByIdRequest {\n    // ID of pet to fetch\n    int64 id = 1;\n}\n\nmessage FindPetByIdResponse {\n    int64 id = 1;\n    string name = 2;\n    string tag = 3;\n}\n\nmessage FindPetsByIdsRequest {\n    repeated string ids = 1;\n\n    // maximum number of results to return\n    int32 limit = 2;\n}\n\nmessage FindPetsByIdsResponse {\n    message PetsMessage {\n        int64 id = 1;\n        string name = 2;\n        string tag = 3;\n    }\n\n    repeated PetsMessage pets = 1;\n}\n\nmessage FindPetsRequest {\n    // maximum number of results to return\n    int32 limit = 1;\n\n    // tags to filter by\n    repeated string tags = 2;\n}\n\nmessage FindPetsResponse {\n    message PetsMessage {\n        int64 id = 1;\n        string name = 2;\n        string tag = 3;\n    }\n\n    repeated PetsMessage pets = 1;\n}\n\nservice SwaggerPetstoreService {\n    // Creates a new pet in the store.  Duplicates are allowed\n    rpc AddPet(AddPetRequest) returns (AddPetResponse) {\n        option (google.api.http) = {\n            post: \"/api/pets\"\n            body: \"pet\"\n        };\n    }\n\n    // deletes a single pet based on the ID supplied\n    rpc DeletePet(DeletePetRequest) returns (google.protobuf.Empty) {\n        option (google.api.http) = {\n            delete: \"/api/pets/{id}\"\n        };\n    }\n\n    // Returns a user based on a single ID, if the user does not have access to the pet\n    rpc FindPetById(FindPetByIdRequest) returns (FindPetByIdResponse) {\n        option (google.api.http) = {\n            get: \"/api/pets/{id}\"\n        };\n    }\n\n    // Returns all pets from the system that the user has access to\n    rpc FindPets(FindPetsRequest) returns (FindPetsResponse) {\n        option (google.api.http) = {\n            get: \"/api/pets\"\n        };\n    }\n\n    // Returns all pets from the system that the user has access to\n    rpc FindPetsByIds(FindPetsByIdsRequest) returns (FindPetsByIdsResponse) {\n        option (google.api.http) = {\n            get: \"/api/pets/{ids}\"\n        };\n    }\n}\n```\n","funding_links":[],"categories":["Protocol Buffers"],"sub_categories":["Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNYTimes%2Fopenapi2proto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNYTimes%2Fopenapi2proto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNYTimes%2Fopenapi2proto/lists"}