代码之家  ›  专栏  ›  技术社区  ›  Jeremy Holovacs

如何从swashbackle的xml文档中生成枚举的描述?

  •  0
  • Jeremy Holovacs  · 技术社区  · 8 年前

    我的.NET核心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
    }
    

    然后,我将swashbuck连接起来,以包含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"
        }
    }
    

    我错过了什么让这工作?我用的是Swashback的v 2.5.0,看起来是最新最棒的。

    1 回复  |  直到 8 年前
        1
  •  2
  •   Helder Sepulveda    8 年前

    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