如何从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 2.5.0版，它看起来是最新的和最大的。

Answer 1

OAS（OpenAPI-Specification）不支持枚举值的注释：

5.5.1.1。 有效值

此关键字的值必须为数组。 此数组必须至少包含一个元素。 数组中的元素必须唯一。

数组中的元素可以是任何类型，包括null。

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