Schema Metadata for C# 9 Records

[RehanSaeed]

C# 9 Positional Records & XML Comments

We can't use positional records with XML comments because there is no way to provide comments for the properties. There is a Roslyn bug open for this at dotnet/roslyn#44571. This would be the ideal solution.

C# 9 Records & XML Comments

We can create init properties instead and comment them as usual. This works.

/// <summary>A product.</summary>
public record Product
{
    /// <summary>Gets or sets the unique identifier.</summary>
    public int Id { get; init; }
}

C# 9 Positional Records & Swagger Annotations

Using the [SwaggerSchema] attribute in a positional record doesn't seem to work. Please can support for this be added?

public record Product([SwaggerSchema("The product identifier")] int Id);

[GoodeUser]

@RehanSaeed You should be able to target the backing property by doing something like this:

public record Product([property: SwaggerSchema("The product identifier")] int Id);

The corresponding documentation for Positional Record Members can be found here: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-9.0/records#positional-record-members

Update (2/24/2022):
This is in the current release preview but until the fix to allow XML param comments on records make it to a stable release (link here), our team has been manually specifying the properties on records (which ain't pretty). An example of a working solution is this:

public record ActiveSessionsPostInput(Guid Pid, Guid Cid, string SessionId)
{
    /// <summary>
    /// The ParentId of the account
    /// </summary>
    public Guid Pid { get; init; } = Pid;

    /// <summary>
    /// The ChildId sending the request
    /// </summary>
    public Guid Cid { get; init; } = Cid;

    /// <summary>
    /// The ID of the current session.
    /// </summary>
    public string SessionId { get; init; } = SessionId;

    public ActiveSession ToActiveSession() => new(Pid, Cid, DateTime.UtcNow, SessionId);
}

[reinux]

@RehanSaeed You should be able to target the backing property by doing something like this:

public record Product([property: SwaggerSchema("The product identifier")] int Id);

The corresponding documentation for Positional Record Members can be found here: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-9.0/records#positional-record-members

This compiles, but it doesn't appear to be picked up by Swashbuckle.

The problem has also been stuck on the C# side since April. dotnet/roslyn#52663

[andy-g]

From my understanding, the issue with XML comments for record properties has been resolved with dotnet 6.

I'm able to compile either of these options:

/// <summary>A product.</summary>
public record Product
{
    /// <summary>Gets or sets the unique identifier.</summary>
    public int Id { get; init; }
}

/// <summary>A product.</summary>
/// <param name = "Id">Gets or sets the unique identifier.</param>
public record Product2
(
    int Id
);

Now that this is supported in a released version of the language, is it possible to support this in Swashbuckle too, to handle both xml comments like this, as well as additional data annotations as outlined in dotnet/AspNetCore.Docs#24858?

There quite a lot of excitement around using records as immutable DTO's etc, which is generally very useful for API requests & responses, but it's quite confusing when the results on the swaggger / redoc output is inconsistent depending on whether a class or record type is used.

Thanks so much.

[voroninp]

@GoodeUser , targeting parameter:

public record Product([property: Required] string Id);

does not work.
Framework throws, because for positional records validation attributes must be applied to constructor parameters. However, Swashbuckle does not recognize nullability of reference types or attribute applied to constructor parameter.

[MJLHThomassenHadrian]

Any updates on this?

[barruka]

I believe it's crucial for the developer community to have this issue resolved, especially since the necessary code to fix it is already available. Documentation is incredibly important when building an API, and it's been three years since the release of .NET 5 with record types. In my opinion, prioritizing the resolution and merging of this issue might be more important than adding new features.