github.com/cbroglie/openapi2proto@v0.0.0-20171004221549-76b8501da882/README.md (about) 1 # openapi2proto [![Build Status](https://travis-ci.org/NYTimes/openapi2proto.svg?branch=master)](https://travis-ci.org/NYTimes/openapi2proto) 2 3 This tool will accept an OpenAPI/Swagger definition (yaml or JSON) and generate a Protobuf v3 schema and gRPC service definition from it. 4 5 ## Install 6 7 To install, have Go installed with `$GOPATH/bin` on your `$PATH` and then: 8 ``` 9 go get -u github.com/NYTimes/openapi2proto/cmd/openapi2proto 10 ``` 11 12 ## Run 13 14 There are 2 CLI flags for using the tool: 15 * `-spec` to point to the appropriate OpenAPI spec file 16 * `-options` to include google.api.http options for [grpc-gateway](https://github.com/gengo/grpc-gateway) users. This is disabled by default. 17 18 ## Protobuf Tags 19 * 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. 20 21 ## External Files 22 * Any externally referenced Open API spec will be fetched and inlined. 23 * Any externally referenced Protobuf files will be added as imports. 24 * Example usage: `$ref: "google/protobuf/timestamp.proto#/google.protobuf.Timestamp"` 25 26 ## Caveats 27 28 * Fields with scalar types that can also be "null" will get wrapped with one of the `google.protobuf.*Value` types. 29 * Fields with that have more than 1 type and the second type is not "null" will be replaced with the `google.protobuf.Any` type. 30 * Endpoints that respond with an array will be wrapped with a message type that has a single field, 'items', that contains the array. 31 * Only "200" and "201" responses are inspected for determining the expected return value for RPC endpoints. 32 * 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 and will have their parent types prepended. 33 34 35 ## Example 36 37 ``` 38 ╰─➤ openapi2proto -spec swagger.yaml -options 39 syntax = "proto3"; 40 41 import "google/protobuf/empty.proto"; 42 43 import "google/api/annotations.proto"; 44 45 package swaggerpetstore; 46 47 message GetPetsRequest { 48 // maximum number of results to return 49 int32 limit = 1; 50 // tags to filter by 51 repeated string tags = 2; 52 } 53 54 message PostPetsRequest { 55 // Pet to add to the store 56 Pet pet = 1; 57 } 58 59 message GetPetsIdRequest { 60 // ID of pet to fetch 61 int64 id = 1; 62 } 63 64 message DeletePetsIdRequest { 65 // ID of pet to delete 66 int64 id = 1; 67 } 68 69 message Pet { 70 int64 id = 1; 71 string name = 2; 72 string tag = 3; 73 } 74 75 message Pets { 76 repeated Pet pets = 1; 77 } 78 79 service SwaggerPetstoreService { 80 // Returns all pets from the system that the user has access to 81 rpc GetPets(GetPetsRequest) returns (Pets) { 82 option (google.api.http) = { 83 get: "/api/pets" 84 }; 85 } 86 // Creates a new pet in the store. Duplicates are allowed 87 rpc PostPets(PostPetsRequest) returns (Pet) { 88 option (google.api.http) = { 89 post: "/api/pets" 90 body: "pet" 91 }; 92 } 93 // Returns a user based on a single ID, if the user does not have access to the pet 94 rpc GetPetsId(GetPetsIdRequest) returns (Pet) { 95 option (google.api.http) = { 96 get: "/api/pets/{id}" 97 }; 98 } 99 // deletes a single pet based on the ID supplied 100 rpc DeletePetsId(DeletePetsIdRequest) returns (google.protobuf.Empty) { 101 option (google.api.http) = { 102 delete: "/api/pets/{id}" 103 }; 104 } 105 } 106 ```