0

I would like to use GraphiQL docs to document my GraphQL API. The out-of-the-box version already looks pretty useful, however I would like to enrich it by the information about permissions.

My imagination is that in this

enter image description here

there will be another section, i.e. "Permissions", with some description of the permissions.

My question: is this the way to do it? If not, how can one express permissions in the GraphiQL Docs? And if this could be the way, is there any tool capable of doing this?

karlosss
  • 2,816
  • 7
  • 26
  • 42

1 Answers1

1

What's shown in GraphiQL (or similar tools like GraphQL Playground, Altair, etc.) is limited to what can be returned through introspection of the schema, which is limited by what the spec specifies. You can add descriptions to types, fields, arguments, enum values and directives. A description for the schema itself is in the works.

At best, you could add a description to your field specifying the permissions. You can use markdown if you want to jazz it up.

Daniel Rearden
  • 80,636
  • 11
  • 185
  • 183
  • Thanks for a fast reply! How do people handle this usually? Another documentation tool? Writing the docs by hand? I believe someone must already have encountered such a problem before... – karlosss Feb 19 '20 at 15:38
  • I doubt there's any tool that would enable you to decorate your schema with arbitrary metadata that would be exposed through the tool's UI. Like I said, if your intent is to annotate what permissions are required for each field, then using the description is the best bet. If you already use a directive to apply the permission scheme, then that same directive could also modify the description dynamically. – Daniel Rearden Feb 19 '20 at 15:52