rmosolgo / graphql-ruby

Ruby implementation of GraphQL
http://graphql-ruby.org
MIT License
5.38k stars 1.39k forks source link

Confusing documentation for plugins #5093

Closed rex-remind101 closed 2 months ago

rex-remind101 commented 2 months ago

Describe the bug

There is a hint of documentation about writing Plugin but no detailed description of what interface or class to inherit to do so https://graphql-ruby.org/schema/definition.html#plugins . I'd like to write a plugin for some connection management but cannot figure out how.

Versions

latest

GraphQL schema

n/a

GraphQL query

n/a

Steps to reproduce

https://graphql-ruby.org/schema/definition.html#plugins

Expected behavior

There's clear documentation on how to implement a plugin.

Actual behavior

There's not clear documentation on how to implement a plugin.

n/a

Additional context

n/a

rmosolgo commented 2 months ago

Hi! Sorry for the confusion and thanks for asking about it. In short, use ... is an API for adding things to your schema. Whatever object is passed to use ... receives a method call like .use(schema, **kwargs), and inside that method, it can do whatever it wants to the passed-in schema.

There's not anything else special about plugins (yet...?), beside that .use call. So you can see a few examples inside GraphQL-Ruby:

https://github.com/rmosolgo/graphql-ruby/blob/f82ed872464bf262dfd184a8e97517b2cb6f0ac6/lib/graphql/backtrace.rb#L26-L28

https://github.com/rmosolgo/graphql-ruby/blob/f82ed872464bf262dfd184a8e97517b2cb6f0ac6/lib/graphql/schema/visibility.rb#L8-L14

https://github.com/rmosolgo/graphql-ruby/blob/f82ed872464bf262dfd184a8e97517b2cb6f0ac6/lib/graphql/schema/timeout.rb#L35-L39

https://github.com/rmosolgo/graphql-ruby/blob/f82ed872464bf262dfd184a8e97517b2cb6f0ac6/lib/graphql/subscriptions.rb#L25-L30

So, there's not really more to say about that. Arguably, that section could be removed from the docs entirely since it's not useful by itself. (That is, all the relevant plugins have documentation for use ...).

If you give that API a try and run into any trouble, please let me know!