How to generate descriptions on enums from XML documentation for Swashbuckle?

Question

I have a model with the following enum in my .NET Core web api project:

public enum Industries
{
    Undefined = 0,

    /// <summary>
    ///    Agriculture, Forestry, Fishing and Hunting
    /// </summary>
    AgricultureForestryFishingAndHunting = 1,

    Mining = 2,

    Utilities = 3,

    Construction = 4,

    /// <summary>
    ///    Computer and Electronics Manufacturing
    /// </summary>
    ComputerAndElectronicsManufacturing = 5,

    /// <summary>
    ///    Other Manufacturing
    /// </summary>
    OtherManufacturing = 6,

    Wholesale = 7,

    Retail = 8,

    /// <summary>
    ///    Transportation and Warehousing
    /// </summary>
    TransportationAndWarehousing = 9,

    Publishing = 10,

    Software = 11,

    Telecommunications = 12,

    Broadcasting = 13,

    /// <summary>
    ///    Information Services and Data Processing
    /// </summary>
    InformationServicesAndDataProcessing = 14,

    /// <summary>
    ///    Other Information Industry
    /// </summary>
    OtherInformationIndustry = 15,

    /// <summary>
    ///    Finance and Insurance
    /// </summary>
    FinanceAndInsurance = 16,

    /// <summary>
    ///    Real Estate, Rental and Leasing
    /// </summary>
    RealEstateRentalAndLeasing = 17,

    /// <summary>
    ///    College, University, and Adult Education
    /// </summary>
    CollegeUniversityAndAdultEducation = 18,

    /// <summary>
    ///    Primary/Secondary (K-12) Education
    /// </summary>
    PrimarySecondaryK12Education = 19,

    /// <summary>
    ///    Other Education Industry
    /// </summary>
    OtherEducationIndustry = 20,

    /// <summary>
    ///    Health Care and Social Assistance
    /// </summary>
    HealthCareAndSocialAssistance = 21,

    /// <summary>
    ///    Arts, Entertainment, and Recreation
    /// </summary>
    ArtsEntertainmentAndRecreation = 22,

    /// <summary>
    ///    Hotel and Food Services
    /// </summary>
    HotelAndFoodServices = 23,

    /// <summary>
    ///    Government and Public Administration
    /// </summary>
    GovernmentAndPublicAdministration = 24,

    /// <summary>
    ///    Legal Services
    /// </summary>
    LegalServices = 25,

    /// <summary>
    ///    Scientific or Technical Services
    /// </summary>
    ScientificorTechnicalServices = 26,

    Homemaker = 27,

    Military = 28,

    Religious = 29,

    /// <summary>
    ///    Other Industry
    /// </summary>
    OtherIndustry = 30
}

I then wire up swashbuckle to include the XML documentation file:

services.AddSwaggerGen(c =>
{
    c.IncludeXmlComments(Path.Combine(AppDomain.CurrentDomain.BaseDirectory,
        "MySolution.xml"), true);

    c.IncludeXmlComments(Path.Combine(AppDomain.CurrentDomain.BaseDirectory,
        "MySolution.Client.xml"), true);

    c.IncludeXmlComments(Path.Combine(AppDomain.CurrentDomain.BaseDirectory,
        "MySolution.Common.xml"), true);

    c.DescribeAllEnumsAsStrings();
    c.SwaggerDoc("v1",
        new Info {Title = "My Solution", Version = "v1"});

    c.DescribeAllParametersInCamelCase();
    c.DescribeStringEnumsInCamelCase();
    c.IgnoreObsoleteProperties();
    c.UseReferencedDefinitionsForEnums();
    c.CustomSchemaIds(x => x.FullName);
});

When running this and viewing the swagger.json document, I don't see my XML comments for the enum values at all, just the values:

"definitions": {
    ...
    "MySolution.Common.Models.Industries": {
        "enum": [
            "undefined",
            "agricultureForestryFishingAndHunting",
            "mining",
            "utilities",
            "construction",
            "computerAndElectronicsManufacturing",
            "otherManufacturing",
            "wholesale",
            "retail",
            "transportationAndWarehousing",
            "publishing",
            "software",
            "telecommunications",
            "broadcasting",
            "informationServicesAndDataProcessing",
            "otherInformationIndustry",
            "financeAndInsurance",
            "realEstateRentalAndLeasing",
            "collegeUniversityAndAdultEducation",
            "primarySecondaryK12Education",
            "otherEducationIndustry",
            "healthCareAndSocialAssistance",
            "artsEntertainmentAndRecreation",
            "hotelAndFoodServices",
            "governmentAndPublicAdministration",
            "legalServices",
            "scientificorTechnicalServices",
            "homemaker",
            "military",
            "religious",
            "otherIndustry"],
        "type": "string"
    }
}

What am I missing to make this work? I'm using v 2.5.0 of Swashbuckle, which looks like the latest and greatest.

Answer 1

Comments for the enum values are not supported by the OAS (OpenAPI-Specification) :

5.5.1.1. Valid values

The value of this keyword MUST be an array. This array MUST have at least one element. Elements in the array MUST be unique.

Elements in the array MAY be of any type, including null.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#items-object https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00#section-5.5.1