Replicate descriptions from interfaces to the types that implement the interface

Describe the problem

Currently, magidoc beautifully displays the descriptions that are present in our GraphQL schema. Our schema makes extensive use of GraphQL interfaces. That is, we’ll define an interface in a common place, and then define concrete types in one or more other model files. As you know, when a type implements an interface, all the field names in the interface must be specified in the type. Because of this, if we add descriptions to the fields in an interface, it would be nice if those descriptions would propagate to the concrete types that implement the interface, presuming the concrete type hasn’t already added a description for the field. This way, we only have to provide a description once, and it will automatically get replicated to the places it applies.

Describe the proposed solution

Either makes this built-in behavior, or provide an option in the mjs config file to control if descriptions are propagated from interfaces to other interfaces or types that implement the interface, if that implementing interface/type doesn’t provide its own.

interface MyInterface {
   """ Interface-provided description of field1 """
   field1: String!

   """ Interface-provided description of field2 """
   field2: String!
}

interface MyType implements MyInterface {
   field1: String!

   """ Type-provided description of field2 """
   field2: String!
}

Given the above schema, when magidoc processes the schema, it would recognize that MyType:field1 does not have a description, so it propagates the description from MyInterface:field1 to MyType:field1. Also, magidoc would recognize that MyType:field2 has provided a description, so magidoc would not copy the description from the MyInterface:field2.

Alternatives considered

It’s possible this functionality could be implemented in a graphql codegen plugin (such as in the schema-ast or introspection plugin). But, if someone isn’t using a codegen plugin, but rather doing a live introspection query, they could not benefit from this behavior.

Importance

would make my life easier

Additional Information

There are many benefits to this functionality. First, for users of the static doc, they will see descriptions all the way from interfaces to the concrete types. For us developers, we only have to write our descriptions once, and get all the benefits of not copy/pasting descriptions from interfaces from concrete implementations.

[BoilerTom90]

I did a quick sanity test of this improvement, and it looks like it’s working. Thanks again for the quick turnaround!

[BoilerTom90]

Thank you for the quick turnaround! I’ll try this first thing tomorrow morning

~~~~~~~~~~~~~~~~~~~ Tom Hoffman

On Tue, Aug 9, 2022 at 7:59 PM Sunny Pelletier @.***> wrote:

There is currently an outage with Github, I will merge and deploy it as soon as possible.

— Reply to this email directly, view it on GitHub https://github.com/magidoc-org/magidoc/issues/143#issuecomment-1210034392, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEDJHP2BNQK4AU4FGADUVGLVYL5GDANCNFSM56B67GOA . You are receiving this because you authored the thread.Message ID: @.***>