Import OpenAPI Schemas in Gradle project

JSON schema inference is great, but it's not perfect. However, more and more APIs offer OpenAPI (Swagger) specifications.

Aside from API endpoints, they also hold Data Models which include all the information about the types that can be returned from or supplied to the API.

Why should we reinvent the wheel and write our own schema inference when we can use the one provided by the API?

Not only will we now get the proper names of the types, but we will also get enums, correct inheritance and overall better type safety.

First of all, you will need the extra dependency:

implementation("org.jetbrains.kotlinx:dataframe-openapi:$dataframe_version")

OpenAPI type schemas can be generated using both methods described above:

@file:ImportDataSchema(
    path = "https://petstore3.swagger.io/api/v3/openapi.json",
    name = "PetStore",
)

import org.jetbrains.kotlinx.dataframe.annotations.ImportDataSchema

dataframes {
    schema {
        data = "https://petstore3.swagger.io/api/v3/openapi.json"
        name = "PetStore"
    }
}

The only difference is that the name provided is now irrelevant, since the type names are provided by the OpenAPI spec. (If you were wondering, yes, the Kotlin DataFrame library can tell the difference between an OpenAPI spec and normal JSON data)

After importing the data schema, you can now start to import any JSON data you like using the generated schemas. For instance, one of the types in the schema above is PetStore.Pet (which can also be explored here), so let's parse some Pets:

val df: DataFrame<PetStore.Pet> =
    PetStore.Pet.readJson("https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available")

Now you will have a correctly typed DataFrame!

You can also always ctrl+click on the PetStore.Pet type to see all the generated schemas.

If you experience any issues with the OpenAPI support (since there are many gotchas and edge-cases when converting something as type-fluid as JSON to a strongly typed language), please open an issue on the GitHub repo.

Last modified: 29 March 2024