ASP.NET Core + fluentValidation
从基础开始
每次写代码， 都想好好的把接口说明规范号， 不幸的是， 拖拖拉拉直到代码已经很庞大了，回过头来添加缺失的文档就是一个艰巨的任务， 嗯， 艰巨到直接忽略了😭。ASP.NET Core支持API文档有了很大的进步， 特别是在一些第三方库的帮助下， 写API文档就像写注释一样简单明了，与代码逻辑一致（很多东西都可以从代码衍生出来。
首先，通过进入项目Properties并单击Build选项卡，确保您的Web项目生成XML文档。
image
开箱即用，这将导致Visual Studio开始警告您项目中每个缺少的XML注释。您可以通过添加上面的1591来取消警告。
image
Swagger只是一个规范，而不是一个实现。它的正式名称是OpenAPI，但是大多数人仍将它称为Swagger。.NET的两个主要实现是Swashbuckle和NSwag。这里我使用Swashbuckle。
打开NuGet包管理器，搜索Swashbuckle.AspNetCore，并将其添加到您的项目中。
image
安装完成后，转到Startup.cs文件并添加几行代码。在ConfigureServices中，提供以下代码：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info() { Title = "Web App", Version = "v1" });
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
然后，在Configure中，添加以下代码行：
app.UseSwagger();
if (env.IsDevelopment())
{
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "Web App V1");
});
}
此时，您可以调试您的应用程序。默认情况下，swashbuckle会为您的应用程序添加一个路径，因此如果您导航到/ swagger，将显示SwaggerUI。
image
using Microsoft.AspNetCore.Mvc;
namespace WebApplication.ApiControllers
{
/// <summary>
/// Verifies that the swagger documentation generator works as expected.
/// </summary>
[Route("api/[controller]")]
[ApiController]
public class TestController : ControllerBase
{
/// <summary>
/// Retrieves test data.
/// </summary>
/// <returns>The test data.</returns>
[HttpGet]
public IActionResult GetTestData()
{
var model = new
{
Message = "Hello, world!"
};
return Ok(model);
}
}
}
再次启动SwaggerUI，我们可以看到列出了新的API端点。
image
请注意，<summary>注释显示在路径旁边。我们可以使用[SwaggerResponse]属性提供有关不同响应的其他信息。
/// <summary>
/// Retrieves test data.
/// </summary>
/// <returns>The test data.</returns>
[HttpGet]
[SwaggerResponse((int)HttpStatusCode.OK, Description = "The data was returned successfully.")]
[SwaggerResponse((int)HttpStatusCode.Unauthorized, Description = "You are not authorized to access this resource.")]
public IActionResult GetTestData()
{
var model = new
{
Message = "Hello, world!"
};
return Ok(model);
}
这将更新swagger文档：
image
我特别喜欢您可以将不同的返回类型关联到每个响应，因此您可以指定成功时返回正常模型但出错时返回错误模型。
注意：在撰写本文时，您必须指定方法（例如，[HttpGet]），否则SwaggerUI将返回错误。
模型验证
Razor（MVC）集成了许多围绕验证的功能，以ModelState和数据注释为中心。随着SPA和WebAPI的引入，我完全停止使用ModelState，并回到在我的API调用顶部编写显式if语句进行验证。
ModelState通过在System.ComponentModel.DataAnnotations命名空间中定义API模型上的数据注释来工作。这些注释涵盖了最常见的验证形式：必填？有最小长度？有最大长度？有效电邮？匹配正则表达式？在真正投入生产的网站，验证可能与业务逻辑本身一样复杂，嗯， 有时候更复杂， 你无法知道到底是什么样的人在使用你的系统。
特性在编译时就是确定的，这意味着您无法轻松执行复杂逻辑。例如，您必须实现自己的验证属性（或从IValidatableObject继承）才能从配置文件或数据库中读取。
现在，让我们考虑一个使用数据注释和IValidatableObject接口的模型：
public class AddressModel : IValidatableObject
{
[Required]
[MaxLength(100)]
public string Line1 { get; set; }
[MaxLength(100)]
public string Line2 { get; set; }
[Required]
[MaxLength(100)]
public string City { get; set; }
[Required]
[MaxLength(2)]
public string State { get; set; }
[Required]
[RegularExpression(@"^\d{5}(-?\d{4})?$")]
public string Zip { get; set; }
public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
{
var stateRepository = (IStateRepository)validationContext.GetService(typeof(IStateRepository));
var state = stateRepository.GetState(State);
if (state == null)
{
yield return new ValidationResult("Unknown state", new[] { nameof(State) });
}
}
}
以下是该模型的swagger文档：
image
我们的AddressModel当然不再是一个简单的POCO，从DI容器中获取IStateRepository很丑陋。另外，随着API倾向于异步操作，这种同步验证变得不可接受。那么，我们是否会回到一英里长的if语句？
FluentValidation为胜利！
如果你像我一样，当Entity Framework 5引入了流畅的配置时，你会非常放心。开发人员可以使用链式方法调用来定义配置，而不是使用讨厌的EDMX文件或更多属性。FluentValidation是一个库，它实现了相同的流畅配置链，但用于验证。
以下是使用FluentValidation 对AddressModel进行的等效验证：
public class AddressModelValidator : AbstractValidator<AddressModel>
{
private readonly IServiceProvider serviceProvider;
public AddressModelValidator(IServiceProvider serviceProvider)
{
this.serviceProvider = serviceProvider;
RuleFor(x => x.Line1).NotEmpty();
RuleFor(x => x.Line1).MaximumLength(100);
RuleFor(x => x.Line2).MaximumLength(100);
RuleFor(x => x.City).NotEmpty();
RuleFor(x => x.City).MaximumLength(100);
RuleFor(x => x.State).NotEmpty();
RuleFor(x => x.State).MaximumLength(2);
RuleFor(x => x.Zip).NotEmpty();
RuleFor(x => x.Zip).Matches(@"^\d{5}(-?\d{4})?$");
RuleFor(x => x.State).MustAsync(IsKnownState).When(x => x.State != null);
}
private async Task<bool> IsKnownState(string abbreviation, CancellationToken token)
{
var stateRepository = serviceProvider.GetRequiredService<IStateRepository>();
var state = await stateRepository.GetStateAsync(abbreviation, token);
return state != null;
}
}
注意我能够轻松地将IServiceProvider注入到构造函数中，这样，我们可以轻松地按需检索依赖项。还可以使用MustAsync提供异步实现来检查提供状态的有效性。
另请注意，我没有直接将IStateRepository接口注入构造函数(也许这样更好？）。这是生命周期范围由依赖注入框架管理的方式的工件。您还会注意到我使用了GetRequiredServices，这是一种扩展方法，可以更轻松地使用IServiceProvider接口。
为了让ASP.NET Core知道使用FluentValidation，我们必须更新Startup.cs再次归档。首先，打开NuGet包管理器并将FluentValidation.AspNetCore添加到您的项目中。在ConfigureServices方法中，将对AddFluentValidation的调用标记到AddMvc方法上。
services.AddMvc()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
.AddFluentValidation(o =>
{
o.RegisterValidatorsFromAssemblyContaining<AddressModelValidator>();
});
好消息是FluentValidation将重用ASP.NET Core提供的依赖注入配置。对RegisterValidatorsFromAssemblyContaining的调用会自动将程序集中的所有验证程序类注册到服务集合中。这就是允许我将IServiceProvider或IValidatorFactory等东西传递给构造函数的原因。该AddFluentValidation方法提供了配置FluentValidation与ASP.NET核心工作的几种方法。
使用Swagger注册FluentValidation
如果再次打开SwaggerUI，您会注意到我们丢失了所有模型验证信息。默认情况下，Swashbuckle只知道如何生成数据注释的文档。
image
幸运的是，其他一些聪明人已经经历了整合Swashbuckle和FluentValidation的痛苦。只需添加MicroElements.Swashbuckle.FluentValidation NuGet包，现在您可以对AddSwaggerGen调用进行简单修改：
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info() { Title = "Web App", Version = "v1" });
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
c.AddFluentValidationRules();
});
这一行代码允许swagger检查您的验证器类，以构建数据注释附带的等效文档。所以现在，当你打开SwaggerUI时，你可以查看原来的相同级别的详细信息：
image
正如我所示，向ASP.NET Core添加API文档非常简单。到目前为止，我喜欢ASP.NET Core的灵活性。
参考
FluentValidation文档 - https://github.com/JeremySkinner/FluentValidation/wiki/a.-Index
Swagger配置 - https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with- swashbuckle？view = aspnetcore-2.1＆tabs = visual-studio％2Cvisual-studio-xml
Swagger / FluentValidation Integration - https://github.com/micro-elements/MicroElements.Swashbuckle.FluentValidation
自定义Swagger文档 - https：// www。 schaeflein.net/adding-implementation-notes-to-swagger-ui-via-swashbuckle-attributes/
ASP.NET模型验证 - https://docs.microsoft.com/en-us/aspnet/core/mvc/models/验证？视图= aspnetcore-2.1
