ReProto Compiler

The ReProto project is a language-neutral protocol specification, aimed towards describing and generating code for handling messages exchanged through JSON-based APIs.

ReProto specifiec an interface description language (IDL) for specifying schemas. These schemas describe the structure of JSON, and can be used to generate data structures in several different languages.

• See Specification for details on what the syntax of .reproto files is.
• See TODO for details on things that still needs to be done.
• See Examples for some example protocol specifications.
• See Config for how to configure ReProto.
• See Integration Tests for some examples of how protocol specifications can be used.

Note: This project is in an Alpha-stage. Things will change a lot.

Supported Backends

• Java (java)
  • Data models using fasterxml jackson (-m fasterxml), and/or lombok (-m lombok).
• JavaScript (js)
  • ES2015 classes, that can be transpiled using babel (see Integration Test).
• Python (python)
  • Plain-python classes, compatible with 2 and 3 for databinding.
• Rust (rust)
  • Serde-based serialization.
• Doc (doc)
  • HTML-based documentation, based from contextual markdown comments.

Examples

Make you have gotten started with Rust.

Build ReProto using cargo:

$> cargo install --path $PWD/cli reproto

This will install reproto into ~/.cargo/bin, make sure it is in your PATH.

The following is an example of how to build documentation for a package.

$> reproto compile doc -o target/doc \
  --path it/test-service/proto \
  --package test \
  --package [email protected] \
  --package [email protected]

$> open target/doc/index.html

For more example, please have a look at our integration tests.

Maven Plugin

A Maven plugin that integrates reproto into the build lifecycle of a maven project.

VIM Plugin

A VIM plugin that provides syntax highlighting.

Testing

This project includes an extensive set of integration tests.

See make help for documentation on what can be done.

Suites are tests which compiled a given set of rules, and compares with expected output.

Projects are complete project tests. These are projects written for various programming languages, and are generally harder to build.

The tool check-project-deps is used to determine which projects your local system can build.

To run all tests, do:

$> make clean all

The IDL

ReProto specifiec an interface description language (IDL) for specifying schemas. These schemas describe the structure of JSON, and can be used to generate data structures in several different languages.

The ReProto IDL is not based on an existing general purpose markup like JSON.

The goal is to have a compact, intuitive, and productive language for writing specifications.

The following is a simple petstore example using ReProto.

/// # ReProto Petstore
///
/// A sample API that uses a petstore as an example to demonstrate features in the ReProto
/// specification
service Petstore {
  "api" {
    /// Returns all pets from the system that the user has access to.
    GET "pets" {
      /// A list of pets.
      returns 200 "application/json" [Pet];
    }
  }
}

type Pet {
  id: unsigned/64;
  name: string;
  tag?: string;
}

You can compile the above into documentation using the following command:

$> reproto compile doc --out petstore-doc --path examples/petstore --package [email protected]

As a comparison the following is a specification using OpenAPI 2.0.

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "name": "Swagger API Team"
    },
    "license": {
      "name": "MIT"
    }
  },
  "host": "petstore.swagger.io",
  "basePath": "/api",
  "schemes": [
    "http"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/pets": {
      "get": {
        "description": "Returns all pets from the system that the user has access to",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "A list of pets.",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Pet"
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Pet": {
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        },
        "tag": {
          "type": "string"
        }
      }
    }
  }
}

If you miss JSON, you can compile the specification to JSON as well.

$> reproto compile json --out petstore-json --path examples/petstore --package [email protected]