(29)ASP.NET Core3.1 Swagger(OpenAPI)
暗断肠 人气:01.什么是Swagger/OpenAPI?
Swagger是一个与语言无关的规范,用于描述REST API。因为Swagger项目已捐赠给OpenAPI计划,所以也叫OpenAPI。它允许计算机和人员了解服务的功能,可以直接在线访问测试API功能。而Swagger UI提供了基于Web的UI,它使用生成的Swagger规范提供有关服务API的信息。Swashbuckle和NSwag均包含Swagger UI的嵌入式版本,因此可使用中间件注册调用将该嵌入式版本托管在ASP.NET Core应用程序当中。Swagger的核心是Swagger规范,默认情况下是名为swagger.json的文档。它由Swagger工具链(或其第三方实现)根据你的服务生成。它描述了API的功能以及使用HTTP对其进行访问的方式。它驱动Swagger UI,并由工具链用来启用发现和客户端代码生成。
2.NET Swagger实现
NET Swagger实现分为两大分类:
●Swashbuckle.AspNetCore是一个开源项目,用于生成ASP.NET Core Web API的Swagger文档。
●NSwag是另一个用于生成Swagger文档并将Swagger UI或ReDoc集成到ASP.NET Core Web API中的开源项目。此外,NSwag 还提供了为API生成C#和TypeScript客户端代码的方法。
但是由于工作比较忙,我就不打算两个类型都讲了,我只选择Swashbuckle.AspNetCore来讲解和演示。
3.Swashbuckle主要组成部分
Swashbuckle有三个主要组成部分:
Swashbuckle.AspNetCore.Swagger:将SwaggerDocument对象公开为JSON终结点的Swagger对象模型和中间件。
Swashbuckle.AspNetCore.SwaggerGen:从路由、控制器和模型直接生成SwaggerDocument对象的Swagger生成器。它通常与Swagger终结点中间件结合,以自动公开Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI:Swagger UI工具的嵌入式版本。它解释Swagger JSON以构建描述Web API功能的可自定义的丰富体验,它包括针对公共方法的内置测试工具。
安装Swashbuckle组件方法有两种:
--PowerShell Install-Package Swashbuckle.AspNetCore -Version 5.0.0
or
--.NET Core CLI dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 5.0.0
4.什么是REST?
我百度一下,度娘解释是:REST是(Representational State Transfer)“表现层状态转移”的缩写,它是由罗伊·菲尔丁(Roy Fielding)提出的,是用来描述创建HTTP API的标准方法,他发现这四种常用的行为“查看(view),创建(create),编辑(edit)和删除(delete)”都可以直接映射到HTTP中已实现的GET、POST、PUT和DELETE方法。
5.配置Swagger中间件
将Swagger生成器添加到Startup.ConfigureServices方法中的服务集合中:
//注册Swagger生成器,定义一个或多个Swagger文档. services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1", Description = "测试描述" }); });
OpenApiInfo对象是用来标识Swagger文档信息(诸如作者、许可证和说明的信息),您还可以自定义您的主题的信息显示在UI上,详情配置,我就不多说,大家可以看官网描述,如上述OpenApilnfo信息配置示例图:
而在启动应用程序后并导航到http://localhost:<port>/swagger/v1/swagger.json。生成的描述终结点的文档显示在Swagger规范(swagger.json)中:
在Startup.Configure方法中,启用中间件为生成的JSON文档和Swagger UI提供服务:
//使中间件能够将生成的Swagger用作JSON端点. app.UseSwagger(); //允许中间件为swagger ui(HTML、JS、CSS等)提供服务,指定swagger JSON端点. app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); });
根据上述配置就能够启用swagger测试API服务接口了,如下图所示:
6.XML注释
swagger还可以把服务API中对应方法名称,实体属性注释给在UI上显示出来,让您更加直观了解每个方法使用信息,并对没有注释每个方法进行警告提示,具体启用XML注释操作在“解决方案资源管理器”中右键单击该项目,然后选择“编辑<project_name>.csproj”,手动将突出显示的行添加到.csproj 文件:
<PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup>
在启用了XML注释后,swagger只会针对没有添加注释每个方法进行警告提示,而添加了注释的方法则不会进行警告提示:
而每个添加了注释的方法会通过在Startup.ConfigureServices/services.AddSwaggerGen中设置Swagger JSON和UI的注释路径后:
//设置Swagger JSON和UI的注释路径.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); c.IncludeXmlComments(xmlPath);
会在项目根目录生成的一个对应项目文件名的XML文件,而文件里面就包含所有已注释的方法,用于UI上显示:
在启动应用程序后,我们会看到每个有注释方法在左侧会有一行文字描述,效果如下图所示:
如果某个方法或者类下面所有方法不想警告提示,可以通过加入#pragma warning disable声明屏蔽警告提示:
加入声明之后,大家会看到警告提示消失了。
7.数据注释
可以使用System.ComponentModel.DataAnnotations命名空间中的属性来标记模型实体,以帮助驱动Swagger UI 组件。将[Required]属性添加到TodoItem类的Name属性:
namespace TodoApi.Models { public class TodoItem { public long Id { get; set; } [Required] public string Name { get; set; } [DefaultValue(false)] public bool IsComplete { get; set; } } }
此属性的状态会更改掉基础JSON架构:
而将[Produces("application/json")]属性添加到API控制器去,这样做的目的是声明控制器的操作支持application/json的响应内容类型:
[Produces("application/json")] [Route("api/[controller]")] [ApiController] public class ValuesController : ControllerBase { /// <summary> /// 获取值 /// </summary> /// <returns></returns> // GET api/values [HttpGet] public async Task<ActionResult<IEnumerable<string>>> Get() { var result = await new GitHubApi().GetUser(); return new string[] { result.id.Value.ToString(), result.login }; } }
“响应内容类型”下拉列表选此内容类型作为控制器的默认GET操作:
Swagger/OpenAPI出现,大大减少开发者调试时间,增加开发者开发效率,让开发者更加方便调试跟直观了解对应服务方法。
参考文献:
Swashbuckle和ASP.NET Core入门
加载全部内容