Introduction: Code-only GraphQL schema generation for Kotlin
More: Author   ReportBugs   

Build Status codecov Maven Central Javadocs Awesome Kotlin Badge

Most GraphQL libraries for the JVM require developers to maintain two sources of truth for their GraphQL API, the schema and the corresponding code (data fetchers and types). Given the similarities between Kotlin and GraphQL, such as the ability to define nullable/non-nullable types, a schema should be able to be generated from Kotlin code without any separate schema specification. graphql-kotlin builds upon graphql-java to allow code-only GraphQL services to be built.

For information on GraphQL, please visit the GraphQL website.

For information on graphql-java, please visit GraphQL Java.


Using a JVM dependency manager, simply link graphql-kotlin to your project.

With Maven:


With Gradle:

compile(group: 'com.expedia', name: 'graphql-kotlin', version: "$latestVersion")


// Your existing Kotlin code

data class Widget(val id: Int, val value: String)

class WidgetQuery {
  fun widgetById(id: Int): Widget? {
    // grabs widget from a data source, might return null

  @Deprecated("Use widgetById")
  fun widgetByValue(value: String): Widget? {
    // grabs widget from a deprecated data source, might return null

class WidgetMutation {
  fun saveWidget(value: String): Widget {
    // Create and save new widget, returns non-null

// Generate the schema

val config = SchemaGeneratorConfig(listOf("org.example"))
val queries = listOf(TopLevelObject(WidgetQuery()))
val mutations = listOf(TopLevelObject(WidgetMutation()))

toSchema(queries, mutations, config)

will generate

schema {
  query: TopLevelQuery
  mutation: TopLevelMutation

type TopLevelQuery {
  widgetById(id: Int!): Widget

  widgetByValue(vale: String!): Widget @deprecated(reason: "Use widgetById")

type TopLevelMutation {
  saveWidget(value: String!): Widget!

type Widget {
  id: Int!
  value: String!


There are more examples and documention in our Wiki or you can view the javadocs for all published versions

If you have a question about something you can not find in our wiki or javadocs, feel free to create an issue and tag it with the question label.


One way to run a GraphQL server is with Spring Boot. A sample Spring Boot app that uses graphql-kotlin, graphql-java-servlet and graphiql is provided in the example folder. All the examples used in this documentation should be available in the sample app.

In order to run it you can run Application.kt directly from your IDE. Alternatively you can also use the Spring Boot maven plugin by running mvn spring-boot:run from the command line. Once the app has started you can explore the example schema by opening GraphiQL endpoint at http://localhost:8080/graphiql.

Support Me
About Me
Google+: Trinea trinea
GitHub: Trinea