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.
To get started you need to download and install Taxi. Download the taxi.zip file and extract it.
Once the file is downloaded and extracted, you need to add it to your path. It will look something like this:
/install-location/taxi/bin
Once the route to the bin file has been added, open a command line/terminal window and run the command below:
taxi
This will install taxi onto your machine and make it available to use.
We are going to create an application from the command line and add taxi into that application. First steps are to cd
into the directory you want your application to be created in.
Now, let's look at creating an application. Run the following command:
mkdir my-project
This will create a project called my-project. In order to initialise taxi, we need to cd
into our project and run:
taxi init
This will bring the latest version of taxi into our project and prompt us with a bunch of fields to fill in. What needs to be filled in?
Project group: com.hello
Project name: demo
Project version: hit enter
Source directory: hit enter
We should be able to see taxi being added to our project, but how do we test this? Well if taxi has been successfully added there will be a taxi.conf
file in our project. In the command line, ensure you are still inside my-project and run ls
, you should see:
src
and taxi.conf
If we run cat taxi.conf
we will see this:
name: demo/hello-worldversion: 0.1.0sourceRoot: src/
Now we can create our first Taxi file, named person.taxi
:
person.taxinamespace demo {type Person {id : PersonId as StringfirstName : FirstName as StringlastName : LastName as String}}
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.
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.