jmirc / graphql-kotlin

Code-only GraphQL schema generation for Kotlin

GraphQL Kotlin

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

For information on GraphQL, please visit the GraphQL website.

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

Installation

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

With Maven:

<dependency>
  <groupId>com.expedia</groupId>
  <artifactId>graphql-kotlin</artifactId>
  <version>${latestVersion}</version>
</dependency>

With Gradle:

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

Usage

// Your existing Kotlin code

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

class WidgetService {
  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 WidgetUpdater {
  fun saveWidget(value: String): Widget {
    // Create and save a new widget, returns non-null
  }
}

// Generate the schema

val config = SchemaGeneratorConfig(supportedPackages = listOf("org.example"))
val queries = listOf(TopLevelObject(WidgetService()))
val mutations = listOf(TopLevelObject(WidgetUpdater()))

toSchema(config, queries, mutations)

will generate

schema {
  query: Query
  mutation: Mutation
}

type Query {
  widgetById(id: Int!): Widget
  
  widgetByValue(vale: String!): Widget @deprecated(reason: "Use widgetById")
}

type Mutation {
  saveWidget(value: String!): Widget!
}

type Widget {
  id: Int!
  value: String!
}

Documentation

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.

Example

One way to run a GraphQL server is with Spring Boot. A sample Spring Boot app that uses Spring Webflux together with graphql-kotlin and graphql-playground 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/playground.