Giter VIP home page Giter VIP logo

openapi2proto's Introduction

openapi2proto Build Status

This tool will accept an OpenAPI/Swagger definition (yaml or JSON) and generate a Protobuf v3 schema and gRPC service definition from it.

Install

To install, have Go installed with $GOPATH/bin on your $PATH and then:

go get -u github.com/NYTimes/openapi2proto/cmd/openapi2proto

Run

There are 4 CLI flags for using the tool:

  • -spec to point to the appropriate OpenAPI spec file
  • -annotate to include (google.api.http options) for grpc-gateway users. This is disabled by default.
  • -out to have the output written to a file rather than Stdout. Defaults to Stdout if this is not specified.
  • -indent to override the default indentation for Protobuf specs of 4 spaces.
  • -skip-rpcs to skip generation of rpcs. These are generated by default.
  • -namespace-enums to enable inserting the enum name as an enum prefix for each value. This is disabled by default.

Protobuf Tags

  • 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.

External Files

  • Any externally referenced Open API spec will be fetched and inlined.
  • Any externally referenced Protobuf files will be added as imports.
    • Example usage: $ref: "google/protobuf/timestamp.proto#/google.protobuf.Timestamp"

Global Options

Protocol Buffer options such as package names are supported via x-global-options key.

x-global-options:
  go_package: myawesomepackage

Will generate:

option go_package = "myawesomepackage"

Extensions

Global extensions may be generated by specifying x-extensions key.

x-extensions:
- base: google.protobuf.MethodOptions
  fields:
  - name: role
    type: string
    number: 50001
  - name: visibility
    type: string
    number: 50002
  - name: timeout
    type: int32
    number: 50003

Will generate:

extend google.protobuf.MethodOptions {
    string role = 50001;
    string visibility = 50002;
    int32 timeout = 50003;
}

Nested extensions are currently not supported.

Method Options

Method options may be generated by specifying the x-options key within each method.

paths:
  /foo
    post:
      x-options:
        bar: baz

Will generate:

    rpc foo(...) returns (...) {
      option (bar) = "baz";
    }

Caveats

  • Fields with scalar types that can also be "null" will get wrapped with one of the google.protobuf.*Value types.
  • Fields with that have more than 1 type and the second type is not "null" will be replaced with the google.protobuf.Any type.
  • Endpoints that respond with an array will be wrapped with a message type that has a single field, 'items', that contains the array.
  • Only "200" and "201" responses are inspected for determining the expected return value for RPC endpoints.
  • To prevent enum collisions and to match the protobuf style guide, enum values will be CAPITALS_WITH_UNDERSCORES and nested enum values will have their parent types prepended to their names.

Example

╰─➤  openapi2proto -spec swagger.yaml -annotate
syntax = "proto3";

package swaggerpetstore;

import "google/api/annotations.proto";
import "google/protobuf/empty.proto";

message AddPetRequest {
    message PetMessage {
        int64 id = 1;
        string name = 2;
        string tag = 3;
    }

    // Pet to add to the store
    PetMessage pet = 1;
}

message AddPetResponse {
    int64 id = 1;
    string name = 2;
    string tag = 3;
}

message DeletePetRequest {
    // ID of pet to delete
    int64 id = 1;
}

message FindPetByIdRequest {
    // ID of pet to fetch
    int64 id = 1;
}

message FindPetByIdResponse {
    int64 id = 1;
    string name = 2;
    string tag = 3;
}

message FindPetsByIdsRequest {
    repeated string ids = 1;

    // maximum number of results to return
    int32 limit = 2;
}

message FindPetsByIdsResponse {
    message PetsMessage {
        int64 id = 1;
        string name = 2;
        string tag = 3;
    }

    repeated PetsMessage pets = 1;
}

message FindPetsRequest {
    // maximum number of results to return
    int32 limit = 1;

    // tags to filter by
    repeated string tags = 2;
}

message FindPetsResponse {
    message PetsMessage {
        int64 id = 1;
        string name = 2;
        string tag = 3;
    }

    repeated PetsMessage pets = 1;
}

service SwaggerPetstoreService {
    // Creates a new pet in the store.  Duplicates are allowed
    rpc AddPet(AddPetRequest) returns (AddPetResponse) {
        option (google.api.http) = {
            post: "/api/pets"
            body: "pet"
        };
    }

    // deletes a single pet based on the ID supplied
    rpc DeletePet(DeletePetRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            delete: "/api/pets/{id}"
        };
    }

    // Returns a user based on a single ID, if the user does not have access to the pet
    rpc FindPetById(FindPetByIdRequest) returns (FindPetByIdResponse) {
        option (google.api.http) = {
            get: "/api/pets/{id}"
        };
    }

    // Returns all pets from the system that the user has access to
    rpc FindPets(FindPetsRequest) returns (FindPetsResponse) {
        option (google.api.http) = {
            get: "/api/pets"
        };
    }

    // Returns all pets from the system that the user has access to
    rpc FindPetsByIds(FindPetsByIdsRequest) returns (FindPetsByIdsResponse) {
        option (google.api.http) = {
            get: "/api/pets/{ids}"
        };
    }
}

openapi2proto's People

Contributors

ballbag22 avatar cbroglie avatar ctborg avatar dnfehren avatar drmaas avatar imjoshholloway avatar jiahaog avatar jkinkead avatar jprobinson avatar lestrrat avatar maksadbek avatar sarahkevinking avatar scottefein avatar sysradium avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.