一、接口注释
1、在控制器和方法上面添加类似下面的注释
/// <summary>
/// 获取天气
/// </summary>
/// <returns></returns>
2、添加GenerateDocumentationFile， 有两种方式
（1）方式一：右键项目--选择属性，然后找到生成包含API文档的文件并勾选（如下图）
DC6EF753825DAF7A73F011100E882985.png
（2）方式二：右键项目 -- 编辑项目文件，然后在PropertyGroup中直接添加键 GenerateDocumentationFile，值为 True
<PropertyGroup>
<GenerateDocumentationFile>True</GenerateDocumentationFile>
</PropertyGroup>
3、在 Program.cs 中找到builder.Services.AddSwaggerGen();，直接替换为下面代码，运行工程即可
builder.Services.AddSwaggerGen(options => {
// 注释
var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
// 第二个参数为是否显示控制器注释,我们选择true
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename), true);
// 生成多个文档显示
typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
{
//添加文档介绍
options.SwaggerDoc(version, new OpenApiInfo
{
Title = $"项目名",
Version = version,
Description = $"项目名:{version}版本"
});
});
});
二、版本控制
1、创建一个枚举类
/// <summary>
/// Api版本枚举类
/// </summary>
public enum ApiVersions
{
/// <summary>
/// 版本V1
/// </summary>
V1 = 1,
/// <summary>
/// 版本V2
/// </summary>
V2 = 2
}
2、在 Program.cs 中找到builder.Services.AddSwaggerGen();，添加替换为如下代码
builder.Services.AddSwaggerGen(options =>
{
// 生成多个文档显示
typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
{
// 添加文档介绍
options.SwaggerDoc(version, new OpenApiInfo
{
Title = $"项目名",
Version = version,
Description = $"项目名:{version}版本"
});
});
});
3、在 Program.cs 中找到builder.Services.UseSwaggerUI();，替换为如下代码
app.UseSwaggerUI(options =>
{
//options.SwaggerEndpoint($"/swagger/V1/swagger.json", $"版本选择:V1");
//如果只有一个版本也要和上方保持一致
typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
{
//切换版本操作
//参数一是使用的哪个json文件,参数二就是个名字
options.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"版本选择:{version}");
});
});
4、在对应方法上添加[ApiExplorerSettings(GroupName = "V1")]，然后运行工程即可
/// <summary>
/// 获取天气
/// </summary>
/// <returns></returns>
[ApiExplorerSettings(GroupName = "V1")]
[HttpGet(Name = "GetWeatherForecast")]
public IEnumerable<WeatherForecast> Get()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
/// <summary>
/// 获取天气版本2
/// </summary>
/// <returns></returns>
[ApiExplorerSettings(GroupName = "V2")]
[HttpGet]
[Route("~/GetWeatherForecast2")]
public IEnumerable<WeatherForecast> Get2()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
swagger.png
