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

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

Answer 1

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

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

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

1 个答案: