Getting started

Taxi is distributed by SDKMAN. If you haven't installed this yet, follow the instructions at SDKMAN's installation page.

Then simply run:

sdk i taxi
taxi

For more information about taxi, including typical project setup, and available commands, head

Creating a taxi project from the command line

taxi has a helpful tool for creating a new project in an empty directory - taxi init.

mkdir hello-world
cd hello-world
taxi init

You'll be prompted with basic project details to name and create your new taxi project

• Project group: demo ⏎
• Project name: hello-world ⏎
• Project version: ⏎ (Defaults are fine)
• Source directory: ⏎ (Defaults are fine)

A new taxi.conf has now been created, as follows:

name: demo/hello-world
version: 0.1.0
sourceRoot: src/

Creating your first taxi file

Create your first Taxi file, named person.taxi:

namespace demo

[[ The first name of a person.  Call them this at dinner time. ]]
type FirstName inherits String

[[ The last name of a person.  Use this when they're in trouble. ]]
type LastName inherits String

[[ A unique id for a person, as each one of us is truly unique. Even you. ]]
type PersonId inherits String

model Person {
   id : PersonId
   firstName : FirstName
   lastName : LastName
}

And create a project file, named taxi.conf:

name: demo/hello-world
version: 0.1.0

Then compile:

taxi build

This simply validates that there are no syntactic errors in your files.

This is enough to start building a taxonomy to describe your organisations data and APIs. You could

You could also push this to a git repository, and use tooling such as Orbital to turn your taxi project into a powerful data catalogue and searchable wiki. Read more about that here

We can also use Taxi's code generators to turn our taxonomy into code - which we'll do now.

Generating code and models from our taxonomy.

Now that we have a simple taxonomy and available, we can use it to generate code.

Taxi ships with a single generator - for emitting Kotlin code - however, you can author your own plugins to generate any code you like from Taxi.

Modify the taxi.conf file, to add the Kotlin plugin. Simply add the following:

plugins {
   taxi/kotlin {
      generatedTypeNamesPackageName: "demo.helloWorld"
      maven {
         artifactId: hello-world
         groupId: "demo"
      }
   }
}

Save, and re-run the build command

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.