如何从 Swashbuckle 的 XML 文档生成关于枚举的描述？

Question

我的 .NET Core web api 项目中有一个包含以下枚举的模型：

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
}

然后我连接 swashbuckle 以包含 XML 文档文件：

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);
});

当运行执行此操作并查看 swagger.json 文档时，我根本看不到我对枚举值的 XML 评论，只有值：

"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"
    }
}

我缺少什么来完成这项工作？我正在使用 Swashbuckle 的 v 2.5.0，它看起来是最新最好的。

Answer 1

OAS（OpenAPI 规范）不支持对枚举值的注释：

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

如何从 Swashbuckle 的 XML 文档生成关于枚举的描述？

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

c#

swagger

.net-core

swashbuckle