Documentation

Documentation allows us to enrich our schema with additional information that is useful for a consumer of our API.

In GraphQL we can do this by providing descriptions to our types, fields, etc.

SDL

type Query {
  "A query field"
  user("An argument" username: String): User
}

"An object type"
type User {
  "A field"
  username: String
}

"An enum"
enum UserRole {
  "An enum value"
  ADMINISTRATOR
}

Usage

We can define descriptions like the following.

[GraphQLDescription("An object type")]
public class User
{
    [GraphQLDescription("A field")]
    public string Username { get; set; }
}

[GraphQLDescription("An enum")]
public enum UserRole
{
    [GraphQLDescription("An enum value")]
    Administrator
}

public class Query
{
    [GraphQLDescription("A query field")]
    public User GetUser(
        [GraphQLDescription("An argument")] string username)
    {
        // Omitted code for brevity
    }
}

If the description provided to the GraphQLDescriptionAttribute is null or made up of only white space, XML documentation comments are used as a fallback.

Learn more about XML documentation below.

XML Documentation

Hot Chocolate provides the ability to automatically generate API documentation from our existing XML documentation.

The following will produce the same schema descriptions we declared above.

/// <summary>
/// An object type
/// </summary>
public class User
{
    /// <summary>
    /// A field
    /// </summary>
    public string Username { get; set; }
}

/// <summary>
/// An enum
/// </summary>
public enum UserRole
{
    /// <summary>
    /// An enum value
    /// </summary>
    Administrator
}

public class Query
{
    /// <summary>
    /// A query field
    /// </summary>
    /// <param name="username">An argument</param>
    public User GetUser(string username)
    {
        // Omitted code for brevity
    }
}

To make the XML documentation available to Hot Chocolate, we have to enable GenerateDocumentationFile in our .csproj file.

XML

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Note: The <NoWarn> element is optional. It prevents the compiler from emitting warnings for missing documentation strings.

If we do not want to include XML documentation in our schema, we can set the UseXmlDocumentation property on the schema's ISchemaOptions.

builder.Services
    .AddGraphQLServer()
    .ModifyOptions(opt => opt.UseXmlDocumentation = false);

With a custom naming convention

If you want to use a custom naming convention and XML documentation, ensure you give the convention an instance of the XmlDocumentationProvider as demonstrated below; otherwise the comments won't appear in your schema.

public class CustomNamingConventions : DefaultNamingConventions
{
    // Before
    public CustomNamingConventions()
        : base() { }

    // After
    public CustomNamingConventions(IDocumentationProvider documentationProvider)
        : base(documentationProvider) { }
}

// Program
// Before
.AddConvention<INamingConventions>(sp => new CustomNamingConventions());

// After
IReadOnlySchemaOptions capturedSchemaOptions;

builder.Services
    .AddGraphQLServer()
    .ModifyOptions(opt => capturedSchemaOptions = opt)
    .AddConvention<INamingConventions>(sp => new CustomNamingConventions(
        new XmlDocumentationProvider(
            new XmlDocumentationFileResolver(
                capturedSchemaOptions.ResolveXmlDocumentationFileName),
            sp.GetApplicationService<ObjectPool<StringBuilder>>()
              ?? new NoOpStringBuilderPool())));

Last updated on 2024-11-20 by Michael Staib