2020-07-30
338 0什么是Swagger?
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger UI允许任何人(无论是您的开发团队还是最终用户)在没有任何实现逻辑的情况下可视化并与API的资源交互。它是根据您的OpenAPI(以前称为Swagger)规范自动生成的,可视化文档使后端实现和客户端使用更加容易。
.Net Core可以通过Nuget轻松安装Swagger组件,使用Swagger UI的强大功能,整个安装过程只需要1分钟,下面跟我来做吧。
Nuget搜索Swashbuckle.AspNetCore安装最新版本。
在Startup.cs里注册服务添加Swagger中间件,代码如下
public void ConfigureServices(IServiceCollection services) { // 添加Swagger服务 services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi Swagger", Version = "v1" }); }); services.AddControllers(); } public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } // 添加Swagger相关中间件 app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1"); }); app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); }
到这里,已经安装完成了,直接按F5调试,然后打开http://localhost:{你的端口号}/swagger/index.html即可访问Swagger UI界面了。
我添加了一个示例控制器UserController,里面有Get,Post,Put,Delete四个Action,示例代码如下
namespace WebApiSwagger.Controllers { [Route("api/[controller]")] [ApiController] public class UserController : ControllerBase { [HttpGet] public string Get(string name) { return $"My name is {name}"; } [HttpPost] public string Post(string name) { return $"Add user {name}"; } [HttpPut] public string Put(int id,string name) { return $"Update user set name as {name} where id is {id}"; } [HttpDelete] public string Delete(string name) { return $"Delete {name}"; } } }
Swagger UI界面如下
如图所示,Swagger UI列出了我的接口信息。
点击某个接口可以查看接口的参数,如图所示,可以接收一个int类型的id和string类型的name参数。点击Try it out可以直接进行接口调用调试了,连PostMan都省了。
如果我们想知道每个方法的注释和方法参数的注释,这就需要对接口做XML注释了。首先安装Microsoft.Extensions.PlatformAbstractions包。
然后Startup.cs里Swagger服务增加一下配置
public void ConfigureServices(IServiceCollection services) { // 添加Swagger服务 services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi Swagger", Version = "v1" }); // 获取xml文件名 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; // 获取xml文件路径 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); // 添加控制器层注释,true表示显示控制器注释 c.IncludeXmlComments(xmlPath, true); }); services.AddControllers(); }
右键项目>属性,在生成菜单里勾选XML文档文件,勾选后,后面输入框里会自动显示xml地址,不需要做修改。如果不勾选直接运行会报错。
然后直接在接口中添加注释就可以了,还是以我UserController接口为例,我对Put方法做了如下修改,从body接收json格式的内容,输出Json。
[HttpPut] public object Put([FromBody]UserRequest request) { return new { success = true, statusCode = 200, message = $"Update user set name as {request.Name} where id is {request.Id}" }; } public class UserRequest { /// <summary> /// 用户Id /// </summary> public int Id { get; set; } /// <summary> /// 用户姓名 /// </summary> public string Name { get; set; } }
运行效果如下,注释显示在接口地址后面了,Request也变成application/json类型了,点击Try it out可以修改Body内容进行调试了。
调试输出Json格式的结果
Swagger更多高级玩法欢迎大家补充。