Documentation improvement

[olivermt]

Is your feature request related to a problem? Please describe.

First off: this project is awesome, so don't take my lengthy complaining as too hard of a criticism :)

There is a lack in the documentation on some common use-cases or if there is documnetation it is referring to the example repository and might show how to do solution X, but suddenly in the context of doing something completely different like using spark instead of spring webflux etc.

I've been coding graphql for years now in various languges (elixir, nodejs etc) and decided to take the leap back into the JVM after a six year hiatus because kotlin tickled my fancy. I know most of the traditional internals that spring use, but it's still a bit unclear what prescriptions you went for, in a library that is pretty prescriptive.

Describe the solution you'd like I'd like the documentation extended with the following basic use-cases

• Data loader as a first class citizen in the documentation. The mixing of dataloader into the spark example makes it very confusing how you are supposed to use and wire this in the 'normal' reflection based resolvers that your main documentation rely on.
• The very common scenario of interacting with the request/response objects. I have been trying all sorts of magic to get at it in the spring webflux default way of using graphql-kotlin and I still have no clue how to get at it. This is most likely a factor of me having not touched modern Spring Boot all that much, but graphql-kotlin as a pretty clean 'standalone' kotlin library for graphql that has pretty noob-friendly documentation all around, this is a pretty glaring hole if you need to do anything that revolves around headers, cookies etc. The current documentation for making your own context sort of let me build my own internal context, and in that factory function I can access the request and response, but I am highly doubtful embedding the request and response into the custom context is the right way to go at it? (If that is the right way, it should be explicitly documented and not included as a trivial example I think :) ) Also, the text "For more details see the Contextual Data documentation." links to a dead url: https://expediagroup.github.io/graphql-kotlin/docs/execution/contextual-data
• Tangential to the one above, there is nothing about how to build security contexts or other request scoped beans to handle user authentication in your current documentation. If the user does not know how to use spring boot with webflux, there is no real path to the goal.

[olivermt]

Also forgot to add, I'd be happy to contribute this if I got some guidance on best ways to go at things :)

[smyrick]

@olivermt Thank you for pointing out these gaps in our documentation. We have been adding documentation pages for features as we add them, but as you pointed out, I think it is time we do a clean pass at all the pages and make sure the docs work well together.

You have pointed out 3 specific areas of focus so I think so would make for 3 great separate PRs. I will keep this issue open and we can work together to make sure we have helpful resources for all our users.

We would also be happy to merge any PR that you open on the docs to help resolve some of the gaps 😄

[olivermt]

Hey!

Superb response :)

I have figured out most of this by trial and error over the weekend and I will compile some outlines to see if you agree that my approaches should be documented as 'best practice'

Then we can have some dialogue and I'll try to type up the actual documentation.

[olivermt]

I have decided I really don't like Spring, after fighting to get Jooq and graphql to work in the same project :D

I am almost done with an end to end (annotation reflection based) setup in ktor now, so I'd rather see if I can help provide some comprehensive documentation there as I think a lot of the "non seasoned" java crowd / startup crew will probably want to come in through that way. Especially since expedia-graphql + a little reflection niceness + ktor is a lot more flexible and un-oppinionated than the ktor-graphql framework I found on github :)

[dariuszkuc]

@olivermt I think it would be great if you could contribute some documentation on it and/or example app to the repo. While Spring is probably the most popular framework out there, there were quite a few inquiries into Ktor support so I'm pretty sure lots of people would appreciate it.

[rrdial]

Hi @olivermt! I'm one of those "non seasoned" java crowd members you're referring to and would love to see some comprehensive documentation and/or example app using ktor.

[smyrick]

If anyone finds this issue and specifically wants to help with adding some Ktor docs, you can assign this issue to yourself to help out the community!

https://github.com/ExpediaGroup/graphql-kotlin/issues/860

[dariuszkuc]

With the creation of common server module (https://github.com/ExpediaGroup/graphql-kotlin/pull/988) we simplified example Ktor and Spring apps and updated documentation (https://expediagroup.github.io/graphql-kotlin/docs/next/getting-started.html).