Generate schema descriptions from XML docstrings

Is your feature request related to a problem? Please describe. Currently the only way to provide descriptions to the GraphQL schema built using Hot Chocolate is through fluent APIs such as overriding the ObjectType<T>.Configure(IObjectTypeDescriptor<T>) method.

Describe the solution you’d like I would like the XML docstrings that are part of my codebase to automatically generate descriptions in the generated GraphQL API. This will reduce the amount of effort required to properly document both my API and the C# code I write. As an example, given the following C# code

/// <summary>
/// Represents a character in the game.
/// </summary>
public class Character
{
    /// <summary>
    /// The name of the character.
    /// </summary>
    public string Name { get; set; }
}

then querying the API’s for the Character type would present the following.

// GraphQL query
query {
  __type(name: "Character") {
    name,
    description,
    fields {
      name,
      description
    }
  }
}

// Response
{
  "data": {
    "__type": {
      "name": "Character",
      "description": "Represents a character in the game."
      "fields": [
        {
          "name": "name",
          "description": "The name of the character."
        }
      ]
    }
  }
}

The XML docstrings could serve as the default description for any types or queries, then be overridden by the fluent APIs.

Describe alternatives you’ve considered

• The primary method of accomplishing this is to write duplicate documentation between XML docstrings and and the fluent APIs, leaving the possibility for inaccurate or mismatching documentation.
• I was able to build some extension methods that use NJsonSchema to pull in property, class, and method XML doc summaries. Although it’s possible to build the functionalities independently, it would be nice for this type of functionality to be supported out of the box.
  • One barrier I’ve encountered is adding descriptions for arguments to methods. If I only include a description then a HotChocolate.SchemaException is thrown due to a null value for the typeReference parameter. This can be overcome by manually including some kind of type mapping. I’m still exploring Hot Chocolate, so perhaps there is already a service/tool that can handle mapping default type mappings to IInputTypes?

Additional context Other open source projects use XML documentation to generate API documentation for Swagger documents. Example projects include NSwag and Swashbuckle.

[michaelstaib]

I have created a documentation task so that we do not forget about it #753

[michaelstaib]

@willwolfram18 have you joined out slack channel?