一、前言
上篇Swashbuckle(一)，主要是讲解的Core中swagger对应框架Swashbuckle的基础使用，本篇文章讲解基于Swashbuckle的进一步实践应用操作和配置。
二、实践技巧
2.1 显示中文注释
Api文档从Xml注释文档中获取描述信息，将基本的信息展示到Swagger UI文档中。
1） 基础配置
编辑项目xxxx.csproj文件，添加如下节点：
<PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn> </PropertyGroup>
修改Configure函数中SwaggerGen中间件服务配置，用于加载xml注释文件配置；
public void ConfigureServices(IServiceCollection services) { .......... services.AddSwaggerGen( options => { //获取当前执行程序集名称+.xml,作为实际xml注释文件名称 string filename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; //拼接路径-路径间隔符由系统决定 string path = System.IO.Path.Combine(System.AppContext.BaseDirectory, filename //添加xml注释文件到swaggergen中用于生成api json options.IncludeXmlComments(path); } ); ......... }
为案例项目中的控制器下Action添加如下内容：
/// <summary> /// 天气预报服务 /// </summary> [ApiController] [Route("[controller]")] public class WeatherForecastController : ControllerBase { ...... /// <summary> /// 获取天气预报信息 /// </summary> /// <returns>天气预报结果</returns> [HttpGet] public IEnumerable<WeatherForecast> Get() { var rng = new Random(); return Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateTime.Now.AddDays(index), TemperatureC = rng.Next(-20, 55), Summary = Summaries[rng.Next(Summaries.Length)] }) .ToArray(); } ...... }
实体类WeatherForecast添加注释：
/// <summary> /// 天气预报实体 /// </summary> public class WeatherForecast { /// <summary> /// 日期 /// </summary> public DateTime Date { get; set; } /// <summary> /// 温度-摄氏度 /// </summary> public int TemperatureC { get; set; } /// <summary> /// 温度-华摄氏度 /// </summary> public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); /// <summary> /// 描述 /// </summary> public string Summary { get; set; } }
重新生成项目后，可以在当前项目的bin/debug文件夹下，查看到对应的xxxx.xml；
<?xml version="1.0"?> <doc> <assembly> <name>swaggertestbase</name> </assembly> <members> <member name="T:swaggertestbase.Controllers.WeatherForecastController"> <summary> 天气预报服务 </summary> </member> <member name="M:swaggertestbase.Controllers.WeatherForecastController.Get"> <summary> 获取天气预报信息 </summary> <returns>天气预报结果</returns> </member> <member name="T:swaggertestbase.WeatherForecast"> <summary> 天气预报实体 </summary> </member> <member name="P:swaggertestbase.WeatherForecast.Date"> <summary> 日期 </summary> </member> <member name="P:swaggertestbase.WeatherForecast.TemperatureC"> <summary> 温度-摄氏度 </summary> </member> <member name="P:swaggertestbase.WeatherForecast.TemperatureF"> <summary> 温度-华摄氏度 </summary> </member> <member name="P:swaggertestbase.WeatherForecast.Summary"> <summary> 描述 </summary> </member> </members> </doc>
运行项目，Api文档如下：
2）添加范例
注释中使用Remarks标记进行范例添加，
/// <summary> /// 天气预报服务 /// </summary> [ApiController] [Route("[controller]")] public class WeatherForecastController : ControllerBase { ...... /// <summary> /// 获取天气预报信息 /// </summary> /// <returns>天气预报结果</returns> /// <remarks> /// 测试范例： /// /// GET /WeatherForecast/ /// /// </remarks> [HttpGet] public IEnumerable<WeatherForecast> Get() { var rng = new Random(); return Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateTime.Now.AddDays(index), TemperatureC = rng.Next(-20, 55), Summary = Summaries[rng.Next(Summaries.Length)] }) .ToArray(); } ...... }
运行效果：
