Welcome to Taxi

Taxi is a language for documenting APIs - the models they return, and the operations they can perform.

As a language, it focuses on:

• Readability - A familiar syntax that should be easy to write, and easy to understand.

• Typesafe - A strongly typed, expressive language, purpose-built for describing API operations & types

• Tooling - Taxi is intended to allow next-generation tooling integration - the syntax allows rich expression of what services can do (rather than just where to find them).

• Extensibility - Taxi allows you to refine and compose API schemas, adding context, annotations, and improving type signatures.

Taxi is used heavily to power Vyne - and the projects have influenced each other & evolved together. The expressiveness of Taxi allows Vyne to automate integration between services.

However, Taxi is intended to be a standalone tool, not coupled to Vyne.

Getting Started

Install the command line tool:

curl -s "https://gitlab.com/taxi-lang/taxi-lang/raw/master/install-cli.py" | python3

Create your first Taxi file, named person.taxi:

person.taxi
namespace demo {
   type Person {
      id : PersonId as String
      firstName : FirstName as String
      lastName : LastName as String
   }
}

And create a project file, named taxi.conf:

taxi.conf
name: demo/hello-world
version: 0.1.0
plugins {
   taxi/kotlin {}
}

Then compile:

taxi build

And you should have some fresh Kotlin files generated, to match your Person object.

This has been a fairly simple example. Take a look at some of the language features to get a better understanding of how Taxi can help you deliver better API documentation.

Swagger & RAML

Taxi draws heavy inspiration from Swagger & RAML, and was born from having spent years working within the Swagger ecosystem, being equally inspired by the project, and frustrated by some of it's limitations.

Taxi aims to be fully compatible with these tools, and exist as a superset of their features. There is a generator for converting Swagger to Taxi, and Taxi to Swagger is on the roadmap.

However, Swagger and RAML leverage general-purpose syntaxes (such as JSON and YAML), Taxi has it's own bespoke language, resulting in much clearer to read API definitions.

While Taxi has a bright future, and there are big plans, it's definitely the new kid on the block - and currently doesn't have feature parity with it's more mature counterparts. However, we intend to address that on the road to 1.0.