Question: Can custom schema directives be shown in generated document?

[ris314]

I would like to surface the @deprecated schema directive references in the generated document based on the SDL file, so that the readers can see deprecation warnings.

In addition, I would like to surface a handful of custom schema directives in the generated document as well. Since I am not relying on the introspection query, I believe this should be possible.

How can achieve this?

[newhouse]

Hello @ris314 and thanks for using SpectaQL!

The @deprecated is supported since it is "built-in" and its significance is easily representable in documentation.

However, custom directives are not currently supported.

1 reason they're not supported is this question: how would they be represented? Would any arguments be shown, or just that they've been decorated with a directive? I suppose some sort of representation would make sense, but I'd need to think about the design perspective a bit, as the UI already feels quite "full" to me right now...

[ris314]

Thanks for the quick response, @newhouse!

I had "spectaql": "^1.4.0" specified in my package.json, and after updating to the latest I can see the @deprecated surfacing. Good stuff.

For custom schema directives display, would you consider interactive elements? For instance, you could render some kind of an indicator/tooltip trigger next to an item and upon hover display detailed information about the invoked directives.

Far be it for me to say what this should look like, just bouncing an idea...

If you decide surfacing custom schema directives is something worthwhile doing and can come up with a good design approach, my only recommendation would be to expose a configuration setting whereby one could whitelist the custom directives to be surfaced in the final output.

[newhouse]

Just an FYI that this currently would only be possible for those that actually provide SpectaQL their SDL file. GraphQL spec does not require servers to add what directives are applied to anything in the schema to the Introspection Query output, so it's not available to SpectaQL in that manner. This puts this a bit lower on my list to support, but I will still keep this open for the future

[rob3000]

@newhouse do you have an example of how this could be done? or a way to add custom metadata. I'd like to be able to add docs such as auth scopes needed in order to use a mutation, thinking a custom directive and adjusting the templates, but not sure how to inject the attribute so that the template can generate it.

[newhouse]

@rob3000 unfortunately, right now there's not really a good way to do this. Without any standard/spec'd way to define what custom directives are applied to a given thing, I'm more hesitant to build support for it.

Right now, the only way to get this information displayed (without cracking open the hood pretty far) would be for you to get what you'd like to display into the description strings. This may not be good enough for you, but if you want to try I see a few options for some sort of support for this for you:

1. You can, of course, put your additional information into the description strings of the things in question. This could make its way to SpectaQL if you ingest via SDL output or Introspection Query Results.
2. If your setup and capabilities allow, you could implement custom directives on your server that could programmatically add the required information to description strings as necessary. This is sort of a "cooler" way to the above bullet point, but likely would not end up in your SDL output, probably limiting SpectaQL's ingestion approach to Introspection Query Results only.