[client] Feedback on graphql-kotlin 3.0.0

I’m just upgrading to graphql-kotlin 3.0.0 to try out using the new client within my integration tests. Here’s some feedback on things that I’m stumbling upon while working on the migration:

• Documentation: https://expediagroup.github.io/graphql-kotlin/docs/client/client-overview

  • Code listing on build.gradle.kts doesn’t work for graphql settings. Should be grahql { client { ... } }
  • The above-mentioned code listing is IMO slightly confusing. AFAIU there are three options on how to retrieve the schema. It would be good to have code listings for each of these options. If there’s only one code listing it should IMO depict the default use-case and state so explicitly, i.e. have a little description about what the listing does right beneath.
  • IMO it would be good to mention the different client-generating tasks in the client overview (graphqlGenerateClient / graphqlGenerateTestClient)

• I’m having trouble working with what should IMO be a typical use-case:

  • Use-case:
    • I have a project that implements a GraphQL API using graphql-kotlin
    • I want to run some integration tests against my backend, via graphql-kotlins client
    • I’d therefore like to download the schema and query files and put them into my source tree / VCS in order to enable backwards-compatibility checks
    • Client should be generated from the schema and query files in my source tree
  • Now, here’s the trouble I’m running into
    • I can’t run “gradle graphqlGenerateTestClient” because the backend is not running
    • I can’t run the backend using “gradle bootRun” because it tries to generate the client which doesn’t work because the backend is not running.
    • Any idea how to solve my issue?
    • From my build.gradle.kts:

graphql {
    client {
        endpoint = "http://localhost:8080/api/graphql"
        packageName = "my.company.myproduct"
        queryFiles = mutableListOf(
            file("path/to/file1.graphql"),
            file("path/to/file3.graphql"),
            file("path/to/file3.graphql")
        )
    }
}

• Trying to solve above-mentioned use case I also tried an approach in which schema and graphql files are stored within my source tree
  • Running gradle graphqlGenerateTestClient fails with: Invalid Syntax : offending token ')' at line 1 column 14
  • From my build.gradle.kts (in addition to the above listing with graphql { client { ... } }):

val graphqlGenerateTestClient by tasks.getting(com.expediagroup.graphql.plugin.gradle.tasks.GraphQLGenerateClientTask::class) {
    packageName.set("com.mycompany.myproduct.client")
    schemaFileName.set("path/to/schema.graphql")
    queryFileDirectory.set("path/to/queries/")
}

• Stack trace shows that error comes from the ANTLR-generated parser:

Caused by: graphql.parser.InvalidSyntaxException: Invalid Syntax : offending token ')' at line 1 column 14
        at graphql.parser.ExtendedBailStrategy.mkException(ExtendedBailStrategy.java:56)
        at graphql.parser.ExtendedBailStrategy.recoverInline(ExtendedBailStrategy.java:33)
        at org.antlr.v4.runtime.Parser.match(Parser.java:206)
        at graphql.parser.antlr.GraphqlParser.variable(GraphqlParser.java:4630)
        at graphql.parser.antlr.GraphqlParser.variableDefinition(GraphqlParser.java:5199)
        at graphql.parser.antlr.GraphqlParser.variableDefinitions(GraphqlParser.java:5137)
        at graphql.parser.antlr.GraphqlParser.operationDefinition(GraphqlParser.java:5062)
        at graphql.parser.antlr.GraphqlParser.definition(GraphqlParser.java:261)
        at graphql.parser.antlr.GraphqlParser.document(GraphqlParser.java:195)
        at graphql.parser.Parser.parseDocument(Parser.java:78)
        at graphql.parser.Parser.parseDocument(Parser.java:39)
        at graphql.parser.Parser.parseDocument(Parser.java:31)
        at com.expediagroup.graphql.plugin.generator.GraphQLClientGenerator.generate(GraphQLClientGenerator.kt:53)
[...]

To sum up my feedback…

1. it would be great if the client documentation could be more of a step-by-step guide for one or multiple concrete typical use cases
2. I have trouble with my use case and I’d appreciate some help 😃

[dariuszkuc]

Thank you for raising. Indeed we missed to update the doc for the client after https://github.com/ExpediaGroup/graphql-kotlin/pull/724. I created https://github.com/ExpediaGroup/graphql-kotlin/pull/739 to fix the config. If documentation is not clear or missing always feel free to raise a PR with updates 😃

[smyrick]

@danbim I am going to close this issue. If you have a specific bug that needs to be resolved let’s create a new issue with details and a branch do demonstrate any issues