一、前言
上篇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();
}
......
}
运行效果:
3)添加响应结果
添加response
节点进行,响应结果的处理,
/// <summary>
/// 天气预报服务
/// </summary>
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
......
/// <summary>
/// 获取天气预报信息
/// </summary>
/// <returns>天气预报结果</returns>
/// <remarks>
/// 测试范例:
///
/// GET /WeatherForecast/
///
/// </remarks>
/// </remarks>
/// <response code="201">请求成功并且服务器创建了新的资源</response>
/// <response code="400">请求失败,错误请求</response>
[HttpGet]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[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();
}
......
}
运行效果:
2.2 提供全局Api
元数据
Api
文档的基础信息,包含文档名称、文档版本、描述信息、团队信息、联系方式、颁发说明。
public void ConfigureServices(IServiceCollection services)
{
..........
services.AddSwaggerGen(
options => {
......
#region 文档元数据
options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo {
Title = "ggcy doc",
Version = "v1",
Description = "this is ggcy doc",
TermsOfService = new System.Uri("https://github.budbud.cn"),
Contact = new Microsoft.OpenApi.Models.OpenApiContact {
Name ="ggcy",
Email = "ggcy@email.com",
Url = new System.Uri("https://github.budbud.cn")
}
});
#endregion
......
}
);
.........
}
Api
文档运行效果如下:
2.3 生成多个Api
文档
对于Api
进行文档分组,在系统运行时,生成多个Api
文档,需要在服务注册时进行配置,在SwaggerGen
扩展函数中进行配置,
public void ConfigureServices(IServiceCollection services)
{
..........
services.AddSwaggerGen(
options => {
......
#region 文档元数据
options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo {
Title = "ggcy doc",
Version = "v1",
Description = "this is ggcy doc",
TermsOfService = new System.Uri("https://github.budbud.cn"),
Contact = new Microsoft.OpenApi.Models.OpenApiContact {
Name ="ggcy",
Email = "ggcy@email.com",
Url = new System.Uri("https://github.budbud.cn")
}
});
//添加分组v2
options.SwaggerDoc("v2", new Microsoft.OpenApi.Models.OpenApiInfo
{
Title = "ggcy v2",
Version = "v2"
});
#endregion
......
}
);
.........
}
1)配置节点
配置中间件SwaggerUI
中对应的请求节点,
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
..........
#region Swagger中间件相关
//添加swagger配置,并启动中间件
app.UseSwagger(options =>
{
options.RouteTemplate = "{documentName}/swaggerapi.json";
}
);
//启用Swagger-ui中间件,并配置swagger json的请求终节点
app.UseSwaggerUI(options => {
options.RoutePrefix = "api-docs";
options.SwaggerEndpoint("/v1/swaggerapi.json","ggcy docs");
//设置swagger-ui对应的节点v2
options.SwaggerEndpoint("/v2/swaggerapi.json","ggcy v2");
});
#endregion
...........
}
2)添加控制器
设定名称为ValuesController
,设置ApiExplorerSettings(GroupName = "v2")
,其中ApiExplorerSettings
既可以作用于控制器类,又可以作用于对应的Action
,
[ApiController]
[Route("api/[controller]")]
[ApiExplorerSettings(GroupName ="v2")]
public class ValuesController : ControllerBase
{
/// <summary>
/// 获取数据信息
/// </summary>
/// <returns>返回结果</returns>
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] {
"O","B","C"
};
}
}
运行效果如下:
v1
v2
由于篇幅较长,剩余内容请查看笔者b
篇。