Generating code from Taxi

This guide explores generating code from your Taxi project. As your usage of Taxi scales, it’s a best practice to extract your types into a standalone, shared taxonomy project.

However, many teams will want to adopt a code-first approach, generating their Service and API specs directly from code (we cover this in detail in our dedicated guide.)

To help with this, Taxi supports generating code from Taxi.

​Creating a Taxi Project

There’s a detailed guide on creating your first Taxi project, so we’ll keep this relatively short. Assuming you’ve already installed Taxi, do the following to create a Taxi project:

mdkir my-taxi-projectcd my-taxi-projecttaxi init

Follow the prompts to create an empty Taxi project, then open the project in your IDE.

​Creating some types

Under the src/ directory, create a file that contains our types. The name of the file doesn’t matter (so long as it has a .taxi extension).

We’ll generate the corresponding types from our code-first-demo

type FilmId inherits Inttype FilmTitle inherits Stringtype ReviewScore inherits Inttype ReviewText inherits String

With this in place, we can run a taxi build to verify that everything compiles. From the command line, in the same directory you ran taxi init in (where a taxi.conf file now sits), run the build command:

taxi build

At this point, you should see something like:

Taxi 1.54.0 @57be173 Fetching dependencies for com.foo/films-api/0.1.0 Compilation succeeded No sources were generated. Consider adding a source generator in the taxi.conf

As the output suggests, no sources have been generated, as we haven’t provided a code generation plugin.

​Generating Kotlin code

Update the taxi.conf file, to add a plugin to generate code for the JVM. The Kotlin code generates code suitable for both Java and Kotlin.

name: com.foo/films-apiversion: 0.1.0sourceRoot: src/additionalSources: {}dependencies: {}plugins: {    taxi/kotlin {}}

Now, running taxi.build will generate Kotlin code for us:

taxi build
Taxi 1.54.0 @57be173 Fetching dependencies for com.foo/films-api/0.1.0 Running generator @taxi/kotlin Generator @taxi/kotlin generated 5 files Compilation succeeded Wrote 5 files to /home/martypitt/dev/tmp/taxi-tutorial/dist

The following files have been created:

Generated Kotlin code

​Generating Maven files

The last missing piece is a pom.xml to let us build this code with Maven.

To update, simply add a maven block into our taxi/kotlin plugin in the taxi.conf file.

name: com.foo/films-apiversion: 0.1.0sourceRoot: src/additionalSources: {}dependencies: {}plugins: {    taxi/kotlin {        maven {}    }}

The maven plugin is very extensible, but we’ll work with the defaults for now.

Note that adding in the Maven plugin means the build will now adopt maven conventions. It’s best to clear out our dist directory before building again.

rm -rf disttaxi build

Generated Maven output

​Consuming in an application

The Kotlin plugin has generated code we can consume in our Java and Kotlin applications.

Using the Spring Boot application from our Spring Boot example, we can update our code to use the generated artefacts, in both our response object definitions, and our API definitions

data class FilmReview(    val score: ReviewScore,    val review: ReviewText)
@GetMapping("/films/{filmId}/review")fun getFilmReview(       @PathVariable("filmId") filmId: FilmId    ): FilmReview {    return FilmReview(        score = Random.nextInt(1,5),        review = listOf("Good","Bad","Meh").random()    )}

These annotations inform the Taxi code generator that to use the correct Taxi type when generating Taxi from code.

For more details on generating taxi from code, see our dedicated guide.

​Summary

This guide has shown you how to create a simple Taxi project, add generate Kotlin (including Java) and Maven code, ready to install and start consuming within your projects.