This plugin is an experiment at this moment. SBT 1.x only
SBT plugin to generate and validate graphql schemas written with Sangria.
See also: https://github.com/mediative/sangria-codegen
This plugin is intended for testing pipelines that ensure that your graphql schema and queries are intact and match. You should also be able to compare it with another schema, e.g. the production schema, to avoid breaking changes.
All features are based on the excellent Sangria GraphQL library
- Schema generation - inspired by mediative/sangria-codegen
- Schema validation - sangria schema validation
- Schema validation against another schema - sangria schema comparison
- Schema release note generation
- Query validation against your locally generated schema - sangria query validation
Add this to your plugins.sbt
and replace the <version>
placeholder with the latest release.
addSbtPlugin("rocks.muki" % "sbt-graphql" % "<version>")
In your build.sbt
enable the plugins and add sangria. I'm using circe as a parser for my json response.
enablePlugins(GraphQLSchemaPlugin, GraphQLQueryPlugin)
libraryDependencies ++= Seq(
"org.sangria-graphql" %% "sangria" % "1.3.0",
"org.sangria-graphql" %% "sangria-circe" % "1.1.0"
)
The schema is generated by accessing the application code via a generated main class that renders
your schema. The main class accesses your code via a small code snippet defined in graphqlSchemaSnippet
.
Example:
My schema is defined in an object called ProductSchema
in a field named schema
.
In your build.sbt
add
graphqlSchemaSnippet := "example.ProductSchema.schema"
Now you can generate a schema with
$ sbt graphqlSchemaGen
You can configure the output directory in your build.sbt
with
target in graphqlSchemaGen := target.value / "graphql-build-schema"
Your build can contain multiple schemas. They are stored in the graphqlSchemas
setting.
This allows to compare arbitrary schemas, write schema.json files for each of them and validate
your queries against them.
There is already one schemas predefined. The build
schema is defined by the graphqlSchemaGen
task.
You can configure the graphqlSchemas
label with
name in graphqlSchemaGen := "local-build"
Schemas are defined via a GraphQLSchema
case class. You need to define
- a
label
. It should be unique and human readable.prod
andbuild
already exist - a
description
. Explain where this schema comes from and what it represents - a
schemaTask
. A sbt task that generates the schema
You can also define a schema from a SchemaLoader
. This requires defining an anonymous sbt task.
graphqlSchemas += GraphQLSchema(
"sangria-example",
"staging schema at http://try.sangria-graphql.org/graphql",
Def.task(
GraphQLSchemaLoader
.fromIntrospection("http://try.sangria-graphql.org/graphql", streams.value.log)
.loadSchema()
).taskValue
)
sbt-graphql
provides a helper object GraphQLSchemaLoader
to load schemas from different
places.
// from a file
graphqlProductionSchema := GraphQLSchemaLoader
.fromFile((resourceManaged in Compile).value / "prod.graphql")
.loadSchema()
// from a graphql endpoint via introspection
graphqlProductionSchema := GraphQLSchemaLoader
.fromIntrospection("http://prod.your-graphql.net/graphql", streams.value.log)
.withHeaders("X-Api-Version" -> "1", "X-Api-Key" -> "4198ab84-e992-42b0-8742-225ed15a781e")
.loadSchema()
The introspection query doesn't support headers at this moment, but will be added soon.
Sangria provides an API for comparing two Schemas. A change can be breaking or not.
The graphqlValidateSchema
tasks compares two given schemas defined in the graphqlSchemas
setting.
graphqlValidateSchema <old schema> <new schema>
You can compare the build
and prod
schema with
$ sbt
> graphqlValidateSchema build prod
You can render every schema with the graphqlRenderSchema
task. In your sbt shell
> graphqlRenderSchema build
This will render the build
schema.
You can configure the target directory with
target in graphqlRenderSchema := target.value / "graphql-schema"
sbt-graphql
creates release notes from changes between two schemas. The format is currently markdown.
$ sbt
> graphqlReleaseNotes <old schema> <new schema>
You can create release notes for the build
and prod
schema with
$ sbt
> graphqlReleaseNotes build prod
The query validation uses the schema generated with graphqlSchemaGen
to validate against all
graphql queries defined under src/main/graphql
. Using separated graphql
files for queries
is inspired by apollo codegen which generates
typings for various languages.
To validate your graphql files run
sbt graphqlValidateQueries
You can change the source directory for your graphql queries with this line in
your build.sbt
sourceDirectory in (Compile, graphqlValidateQueries) := file("path/to/graphql")
You can try out your changes immediately with the test-project
:
$ cd test-project
sbt
If you change code in the plugin you need to reload
the test-project.
Push a tag vX.Y.Z
a travis will automatically release it.
If you push to the snapshot
branch a snapshot version (using the git sha)
will be published.
The git.baseVersion := "x.y.z"
setting configures the base version for
snapshot releases.