Code generation question

[benmccann]

Hi @muuki88, thanks for providing this!

I had a question about getting started. In my build.sbt I added enablePlugins(GraphQLCodegenPlugin) and nothing else related to the plugin because I have a file src/main/resources/schema.graphql, which I believe is the default value. I ran sbt graphqlCodegenSchema, but nothing happened. I didn't understand if anything else was required. Am I missing something?

[muuki88]

Thanks @benmccann ♥️

The codegen generates code for queries. A schema is required to resolve the typings. So without any queries there won't be any code generated 😊

[benmccann]

I do have queries defined in my schema. Or do you mean something else like I need to write queries in my code first?

[felixbr]

A schema doesn't contain queries. A query is something the client sends to the server (which defines the schema) in order to receive a piece of data or trigger some action.

A query looks like this:

query GraphQLProject {
  project(name: "GraphQL") {
    tagline
  }
}

edit: To put it simply: The server defines the schema, the client defines the queries against the schema. This plugin can help you bridge the gap between the two (for example by generating code or by validating that the query can be answered by the schema).

[benmccann]

Ah. I was thinking queries were specified in the schema like this: https://graphql.org/learn/schema/#the-query-and-mutation-types

Example: https://github.com/apollographql/starwars-server/blob/0b61197a0c857c4c09d90176fcdd9e00707e6c16/data/swapiSchema.js#L34

But I might have the terminology wrong. I'm just getting started with GraphQL.

I was assuming GraphQLCodegenPlugin generated types for the server to use in creating the API, but now I'm wondering if it's generating the client-side code instead?

[felixbr]

Ah yes, I can see how the naming is a bit confusing. Let me rephrase it a bit:

The schema contains all fields (which have types) that you can use. There is a distinction between those that only fetch data (called Queries) and those that modify data or trigger actions (called Mutations). This is similar to GET and POST/PUT in REST APIs.

On the client-side you write a string which describes what you want and this is what you send to the server (sangria calls this Document but it's usually called query, hence the confusion).

As you correctly derived, the GraphQLCodegenPlugin is used to generate code for a specific query (as in Document), so you can fill in the input data, send it to the server and get back data which is already deserialized into the generated types.

If you want to create an API, then you don't need this plugin at all, you just use sangria, which has macros that can help you generate a Schema (which is basically your API when we talk about GraphQL) from your types. Personally I'd recommend not using the macros in the beginning, so you see how sangria works but it's your decision.

All in all, it sounds more complicated then it really is. On the server you define your Schema and on the client you write a query to use it and send it to the server:

val schema = Schema(
  queries = List(
    Field("foo", StringType, resolve = _ => "foo!")
  ),
  mutations = List.empty
)

From the client you send a query which requests the field:

query MyQuery {
  foo
}

And you get back something like:

{
  "data": {
    "foo": "foo!"
  },
  "errors": []
}

Hope this clears things up a bit :)