Directive-driven documentation and metadata?

Hello! I just tried spectaql for the first time, and it successfully generated nice-looking (but bare bones) documentation for my rather large API (5288 lines of SDL)!

My GraphQL service is entirely SDL-first, with C/U/D mutations, SQL schema, and most Typescript resolver code generated based on directive-annotated SDL, so it contains many directives that declare semantics, validation, etc. Therefore, I’m wondering whether you have considered or have recommendations on how one might supply metadata (such as undocumented) or generate documentation snippets (e.g. “This field is read-only and has a maximum length of 40 characters.”) using directives.

Obviously, there are very few standard directives (such as @deprecated), so most will be project/framework-specific. Therefore, custom code would likely be required to map a given set of directives onto the metadata supported by the documentation formatter. I think the question basically comes down to whether there is or could be a single place to hook up this user-supplied mapping function.

Another possibility would be to have a separate tool generate JSON metadata for spectaql based on SDL directives. That would work for the existing metadata features of examples and documented/undocumented. To support generated descriptions, I think additional metadata would be needed, such as descriptionPrefix and/or descriptionSuffix. Alternatively, the tool could also generate a new SDL file with generated descriptions inserted. This separate tool approach involves fewer or even no changes to spectaql, but likely involves more work to develop and use.

Anyway, just wondering if this is on your radar. If it sounds interesting and you can suggest how/where to support it, I’m happy to create a PR.

For sake of argument, here’s an example type declaration with directives:

type ContactAddress {
  id: ID! @rid # random base-62 ID
  principal: Principal! @immutable
  organization: Organization @immutable
  type: AddressType! @immutable
  address: String! @length(max: 255)
  label: String @length(max: 40)
  visibility: Visibility!
  systemUse: Boolean! @default(value: "false")
  createDate: DateTime! @sqlType(type: "timestamp") @createdAt
  lastVerified: DateTime @sqlType(type: "timestamp") @readonly
  _id: Int! @id @autoinc @undocumented
}

[newhouse]

OK @trevorr @gonzalezzfelipe @stephen-opal @rajington

I have added support for adding metadata in via a @spectaql directive. The usage is pretty straightforward, and reasonably customizable. It is now out in main and in version 1.5.0.

I decided to make the options you pass a more generic LIST of objects that have the following shape: { key: String!, value: String! }. This will allow for a bit more flexibility, IMO, even though it requires a bit more verbosity/verboseness to write.

Please see https://github.com/anvilco/spectaql#the-spectaql-directive for more information, and let me know how it works for you!

[gonzalezzfelipe]

@gonzalezzfelipe Is it working for you?

Yep, it is working just fine 👍