Improving the documentation about auth HOT 5 OPEN

Would you be interested in helping refine the documentation?

I'd love to take a stab at it.

from auth.

To share some real user thoughts I'm currently hitting while implementing. Where I can't figure out when applyPolicy is even called. I was thinking it would be called anytime a query with the @auth directive on it existed, but I can't seem to get it to fire at all.

Edit: Turns out codegen was stripping the directives from the schema, so I was doing things correctly. On that note of docs though, it might be helpful to give a ELI5 difference between the external and directive based options, as well as a plain english descriptions for things, ie. "applyPolicy is run every time..."

Some more thoughts here. In the examples we show the directive with a parameter
add(x: Int, y: Int): Int @auth(requires: USER)
but in the applyPolicy,

async applyPolicy (authDirectiveAST, parent, args, context, info) {
    return context.auth.identity === 'admin'
  },

This is hardcoded as === 'admin'. So just glancing, the question I wonder is how does the requires: USER connect to the applyPolicy statement.

In this case is authDirectiveAST.arguments[0].value.value the best way to access the directive value? Or am I missing something.

Sorry for the ramble, but as a new user these are the things I'm hitting.

from auth.

Thanks for the feedback, that's super helpful! :)

To summarise your key points:

• Better description on the difference between external and directive options
• Make sure the examples better match the intended schema
• Add some examples on the best way to access the directive value (note, this is currently the best way as we should have everything from the AST). We could maybe expose some helpers for this perhaps? In general, I think we could provide some more usage example here!

Would you be interested in helping refine the documentation?

from auth.

Awesome! Feel free to drop a draft PR in the repo and we can work on it together :)

from auth.

@stolinski I was thinking of starting this work later this week, would you be still interested in helping out?

from auth.