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 specifies a DSL that described JSON types and services. Using this, models can be generated using multiple different target 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 build

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

Build documentation:

$> target/debug/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 ReProto DSL

The goal is to provide an intuitive and productive specification language. For this reason, ReProto uses a DSL that is not based on existing markup (JSON, YAML, ...). This is also reduces the signal to noise ratio.

As a comparison, the following is a specification using OpenAPI 2.0, compared with ReProto.

{
  "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"
        }
      }
    }
  }
}

/// # 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 [Pet] {
        status 200;
        produces "application/json";
      }
    }
  }
}

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

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

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

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

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