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  ```