Swagger是一个支持Rest Api的，用于可视化。也就是说你的WebApi必须遵循RestApi架构风格，否则是无法生成Api文档的
依赖包：
Swashbuckle.Aspnetcore：用于生成Swagger文档
Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer：用户版本控制
因为接口会不断的升级，迭代，所以必然会有版本控制，这样新的版本不会影响就的版本
所以，我这里一开始就会搭建一个版本控制
创建Api项目，默认会有Value控制器，然后分别添加v1和v2文件夹，创建ManagerController
添加版本控制类，添加CustomApiVersion类
namespace SwaggerApi.SwaggerHelper
{
/// <summary>
/// 自定义版本
/// </summary>
public class CustomApiVersion
{
/// <summary>
/// Api接口版本 自定义
/// </summary>
public enum ApiVersions
{
/// <summary>
/// v1 版本
/// </summary>
v1 = ,
/// <summary>
/// v2 版本
/// </summary>
v2 = ,
}
}
}
然后在控制器上通过ApiExplorerSettings分组，就是说明该控制器是那个版本组
创建用于测试的实体类：
namespace SwaggerApi.Models
{
public class Student
{
/// <summary>
/// 用户Id
/// </summary>
public int Id { get; set; }
/// <summary>
/// 用户姓名
/// </summary>
/// <example>示例</example>
public string UserName { get; set; }
/// <summary>
/// 用户名年龄
/// </summary>
public int Age { get; set; } /// <summary>
/// 性别
/// <remarks>
/// 0：男
/// 1：女
/// 2：其他
/// </remarks>
/// </summary> public Gender Gender { get; set; }
} public enum Gender
{
/// <summary>
/// 男
/// </summary>
M = ,
/// <summary>
/// 女
/// </summary>
F = ,
/// <summary>
/// 其他
/// </summary>
O =
} }
注册中间件:
services.AddSwaggerGen(opt =>
{
//遍历出全部的版本，做文档信息展示
typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
{
opt.SwaggerDoc(version, new Info
{
// {ApiName} 定义成全局变量，方便修改
Version = version,
Title = $"{ApiName} 接口文档",
Description = $"{ApiName} HTTP API " + version,
TermsOfService = "None",
Contact = new Contact
{
Name = "糯米粥",
Email = "nsky@cnblogs.com",
Url = "http://www.cnblogs.com/nsky"
}
});
// 按相对路径排序，
opt.OrderActionsBy(o => o.RelativePath); var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
opt.IncludeXmlComments(xmlPath, true);
});
使用中间件:
//允许中间件作为JSON端点为生成的Swagger提供服务。
app.UseSwagger(); //配置swaggerui信息
app.UseSwaggerUI(options =>
{
#region 单个版本控制
//options.SwaggerEndpoint("/swagger/v1/swagger.json", "Api_v1");
//s.RoutePrefix = string.Empty;
#endregion #region 多版本控制 typeof(ApiVersions).GetEnumNames().OrderByDescending(e => e).ToList().ForEach(version =>
{
options.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{ApiName} {version}");
}); //foreach (var description in provider.ApiVersionDescriptions)
//{
// options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
//}
#endregion
});
配置XML注释，右键属性，生成界面：
但如果有的方法没有xml注释，则会由1591警告信息
也可以在属性界面设置:
一起准备完成，就是在Api代码写逻辑了，为了区分v1和v2的不同
可以看到我上面用了CustomRoute自定义类，待会讲，参考网上的做法
运行项目，有2个版本的切换
路径是这样的：
如果不想输入swagger，可以修改路由，把前缀RoutePrefix 清空，即可
可以看到，values不属于任何一个版本，所以，v1和v2都包含了。算是公共的api
现在测试下：