如何从 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
}

然后，我将虚张声势连接到包含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. 有效值

此关键字的值必须是数组。 此数组必须具有 至少一个元素。 数组中的元素必须是唯一的。

数组中的元素可以是任何类型的，包括 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