Support hooks to add custom documentation to objects, fields, arguments and enum values

We came up with a documentation technique that works well for us (syncing both development teams and our product documentation team). We’re trying to resolve the relevant Markdown documentation for each object, field, argument and enum value.

SchemaGeneratorHooks is an awesome general purpose vehicle for intercepting schema generation. I think it can be very helpful in this case, but it would have to be extended to include hook methods that would allow me to augment builder objects just before calling build(). That way I can call the builders’ description method and add my own documentation. Specifically I’m asking for the inclusion of the following hooks:

fun willGenerateGraphQLObject(objectName: String, builder: graphql.schema.GraphQLObjectType.Builder): graphql.schema.GraphQLObjectType.Builder = builder

fun willGenerateGraphQLField(objectName: String, fieldName: String, builder: graphql.schema.GraphQLFieldDefinition.Builder): graphql.schema.GraphQLFieldDefinition.Builder = builder

fun willGenerateGraphQLEnumType(enumName: String, builder: graphql.schema.GraphQLEnumType.Builder): graphql.schema.GraphQLEnumType.Builder = builder

fun willGenerateGraphQLEnumValue(enumName: String, enumValue: String, builder: graphql.schema.GraphQLEnumValueDefinition.Builder): graphql.schema.GraphQLEnumValueDefinition.Builder = builder

fun willGenerateGraphQLArgument(objectName: String, fieldName: String, argumentName: String, builder: graphql.schema.GraphQLArgument.Builder): graphql.schema.GraphQLArgument.Builder = builder

I added the names of the objects/fields/arguments/enums to the hooks’ contexts since it’s difficult to extract that information from the builders directly.

What do you think?

Thanks a lot for a fantastic library!

[smyrick]

@liqweed You can access the name of the generatedType since at this point in the hook, it is fully generated. You can also look at the info on the KType but that is not always the most accurate if you are using this like @GraphQLName to override the type name. You don’t have to traverse any builder, but if you want to edit the type, you can pass it into a new builder and edit the fields that way to produce a new generated GraphQLType

---

@rharriso This hook can be used at this point to add any more info to the type, not just documentation. We already have a way to do custom directives, documented here: https://github.com/ExpediaDotCom/graphql-kotlin/wiki/Schema-Directives

The comment you are referring to is a way to expose a config method or setting to provide a list of pre-configured directives instead of using the onRewireGraphQLType. There are slightly different issues.

[smyrick]

@liqweed These seems like a valid error, I have created a new issue which is open for anyone to work on https://github.com/ExpediaDotCom/graphql-kotlin/issues/281