AspnetCore WebApi使用Swagger简单入门

微软官网入门:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-2.2

Swagger是一个支持Rest Api的,用于可视化。也就是说你的WebApi必须遵循RestApi架构风格,否则是无法生成Api文档的

依赖包:

Swashbuckle.Aspnetcore:用于生成Swagger文档

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer:用户版本控制

因为接口会不断的升级,迭代,所以必然会有版本控制,这样新的版本不会影响就的版本

所以,我这里一开始就会搭建一个版本控制

创建Api项目,默认会有Value控制器,然后分别添加v1和v2文件夹,创建ManagerController

AspnetCore WebApi使用Swagger简单入门

添加版本控制类,添加CustomApiVersion类

namespace SwaggerApi.SwaggerHelper
{
/// <summary>
/// 自定义版本
/// </summary>
public class CustomApiVersion
{
/// <summary>
/// Api接口版本 自定义
/// </summary>
public enum ApiVersions
{
/// <summary>
/// v1 版本
/// </summary>
v1 = ,
/// <summary>
/// v2 版本
/// </summary>
v2 = ,
}
}
}

然后在控制器上通过ApiExplorerSettings分组,就是说明该控制器是那个版本组

AspnetCore WebApi使用Swagger简单入门

创建用于测试的实体类:

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注释,右键属性,生成界面:
AspnetCore WebApi使用Swagger简单入门

但如果有的方法没有xml注释,则会由1591警告信息

AspnetCore WebApi使用Swagger简单入门

也可以在属性界面设置:

AspnetCore WebApi使用Swagger简单入门

一起准备完成,就是在Api代码写逻辑了,为了区分v1和v2的不同

AspnetCore WebApi使用Swagger简单入门

AspnetCore WebApi使用Swagger简单入门

可以看到我上面用了CustomRoute自定义类,待会讲,参考网上的做法

运行项目,有2个版本的切换

AspnetCore WebApi使用Swagger简单入门

路径是这样的:

AspnetCore WebApi使用Swagger简单入门

如果不想输入swagger,可以修改路由,把前缀RoutePrefix 清空,即可

AspnetCore WebApi使用Swagger简单入门

可以看到,values不属于任何一个版本,所以,v1和v2都包含了。算是公共的api

AspnetCore WebApi使用Swagger简单入门

AspnetCore WebApi使用Swagger简单入门

现在测试下:

AspnetCore WebApi使用Swagger简单入门

github:https://github.com/byniqing/AspNetCore-Swagger

上一篇:error MSB8008: 指定的平台工具集(v110)未安装或无效


下一篇:从无到有,用Nodejs+express+mongodb搭建简易登陆系统