【Core Swagger】.NET Core中使用swagger

一.入门

https://www.nuget.org/packages/Swashbuckle.AspNetCore.SwaggerGen/

1.添加核心NUGET包 Swashbuckle.AspNetCore：

2.startup中配置：

ConfigureServices中：

           //注册swagger生成器，定义一个或多个swagger文档services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", new Info{Version = "v1",Title = "测试 API",Description = "A simple example ASP.NET Core Web API",TermsOfService = "None",Contact = new Contact { Name = "ck", Email = "", Url = "http://www.cnblogs.com/chuankang/" },License = new License { Name = "博客园", Url = "http://www.cnblogs.com/chuankang/" }});// api描述文档xml的生成地址和文件名，需要在项目的属性中进行配置var basePath = AppContext.BaseDirectory;var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");if (File.Exists(xmlPath)){c.IncludeXmlComments(xmlPath);}});

Configure中：

　　　　　　  // 启用中间件以生成JSON作为JSON端点.
            app.UseSwagger();// 启用中间件以提供用户界面（HTML、js、CSS等），特别是指定JSON端点。app.UseSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");//页面头名称c.DocumentTitle = "平台API";//页面API文档格式 Full=全部展开， List=只展开列表, None=都不展开
                c.DocExpansion(DocExpansion.List);});

注意：c.SwaggerDoc的第一个参数要和 c.SwaggerEndpoint第一个参数字符串swagger/后面的对应，本例用的是v1

3.api描述文档xml的生成地址和文件名，需要在项目的属性中进行配置，右键项目-> 属性-> 生成如下图：

加上1591忽略属性类名必须加xml注释

4.在controller中action方法都要指定http请求Post（新增）,Put（修改）,Delete（删除）,Get（查询)中的一个，不然会报错：
http://localhost:55642/swagger/v1/swagger.json 浏览器F12控制台查看错误原因

5.启动看效果：

6.每次输入/swagger太麻烦，可以设置借助vs进行跳转，如下图加上 "launchUrl": "swagger" ：

7.如果controller继承了自己定义的基类controller，要为自己定义的方法加上NonActionFillter，因为swagger要为每个action添加http mehod

二.设置多个API版本

ConfigureServices中： c.SwaggerDoc("v2", new Info{Version = "v2",Title = "API 版本2"});
Configure中：
c.SwaggerEndpoint("/swagger/v2/swagger.json", "API V2");

在action上指定版本，不指定版本的action在所有版本中都显示

三.修改默认路由

swagger给我们默认的路由是：http://localhost:49833/swagger/index.html

如果有很多个API项目怎么区分呢？我们可以指定路由把swagger替换掉

那么我们现在应该请求的路由为：http://localhost:49833/test/index.html

四.忽略过时的接口

为action指定Obsolete特性表示过时了，但并不表示不可以使用

运行：

怎么把这过时的接口不显示在swagger页面呢？

只需要在生成器中加入options.IgnoreObsoleteActions();属性就行了

五.忽略某个Api，不在ui页面中显示

六.仅获取某个Http请求的action

例如下面只获取HttpGet请求的接口显示在界面上

// ApiExplorerGetsOnlyConvention.cs
public class ApiExplorerGetsOnlyConvention : IActionModelConvention
{public void Apply(ActionModel action){action.ApiExplorer.IsVisible = action.Attributes.OfType<HttpGetAttribute>().Any();}
}// Startup.cs
public void ConfigureServices(IServiceCollection services)
{services.AddMvc(c =>c.Conventions.Add(new ApiExplorerGetsOnlyConvention()));...
}

七.对action根据Http请求进行分组

services.AddSwaggerGen(c =>
{...c.TagActionsBy(api => api.HttpMethod);
};

八.指定接口排序规则

services.AddSwaggerGen(c =>
{...c.OrderActionsBy((apiDesc) => $"{apiDesc.ActionDescriptor.RouteValues["controller"]}_{apiDesc.HttpMethod}");
};

九.安装并启用注释

安装nuget Swashbuckle.AspNetCore.Annotations

启用：

services.AddSwaggerGen(c =>
{...c.EnableAnnotations();
});

为controller加注释

为action加注释

[HttpPost][SwaggerOperation(Summary = "Creates a new product",Description = "Requires admin privileges",OperationId = "CreateProduct",Tags = new[] { "Purchase", "Products" }
)]
public IActionResult Create([FromBody]Product product)

为响应加验证

[HttpPost]
[SwaggerResponse(201, "The product was created", typeof(Product))]
[SwaggerResponse(400, "The product data is invalid")]
public IActionResult Create([FromBody]Product product)

十.Token验证

ConfigureServices添加

 public void ConfigureServices(IServiceCollection services){#region swaggerservices.AddSwaggerGen(c =>{//启用注释nuget包
                c.EnableAnnotations();c.SwaggerDoc("WebApiA", new Info { Title = "用户API接口A", Version = "v1" });//var basePath = PlatformServices.Default.Application.ApplicationBasePath;string basePath = AppContext.BaseDirectory;//Linux路径区分大小写，这里用appcontextstring xmlPath = Path.Combine(basePath, "WebApiA.xml");//如果有xml注释文档就读取，需在项目属性生成xmlif (File.Exists(xmlPath)){c.IncludeXmlComments(xmlPath);}#region Token绑定到ConfigureServices//添加header验证信息//c.OperationFilter<SwaggerHeader>();var security = new Dictionary<string, IEnumerable<string>> { { "Blog.Core", new string[] { } }, };c.AddSecurityRequirement(security);//方案名称“Blog.Core”可自定义，上下一致即可c.AddSecurityDefinition("Blog.Core", new ApiKeyScheme{Description = "JWT授权(数据将在请求头中进行传输) 直接在下框中输入{token}\"",Name = "Authorization",//jwt默认的参数名称In = "header",//jwt默认存放Authorization信息的位置(请求头中)Type = "apiKey"});#endregion});#endregion#region Token服务注册services.AddSingleton<IMemoryCache>(factory =>{var cache = new MemoryCache(new MemoryCacheOptions());return cache;});services.AddAuthorization(options =>{options.AddPolicy("Client", policy => policy.RequireRole("Client").Build());options.AddPolicy("Admin", policy => policy.RequireRole("Admin").Build());options.AddPolicy("AdminOrClient", policy => policy.RequireRole("Admin,Client").Build());});#endregionservices.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);}

启动：

每次请求时，从Header报文中，获取密钥token，这里根据token可以进一步判断相应的权限等

添加类

JwtHelper：

using Microsoft.IdentityModel.Tokens;
using System;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using WebApiA.Models;namespace WebApiA.AuthHelper
{/// <summary>/// JWT序列化和反序列化/// </summary>public class JwtHelper{public static string SecretKey { get; set; } = "sdfsdfsrty45634kkhllghtdgdfss345t678fs";/// <summary>/// 颁发JWT字符串 /// </summary>/// <param name="tokenModel"></param>/// <returns></returns>public static string IssueJWT(TokenModelJWT tokenModel){var dateTime = DateTime.UtcNow;var claims = new Claim[]{new Claim(JwtRegisteredClaimNames.Jti,tokenModel.Uid.ToString()),//Idnew Claim("Role", tokenModel.Role),//角色new Claim(JwtRegisteredClaimNames.Iat,dateTime.ToString(),ClaimValueTypes.Integer64)};//秘钥var key = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(JwtHelper.SecretKey));var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);var jwt = new JwtSecurityToken(issuer: "Blog.Core",claims: claims, //声明集合expires: dateTime.AddHours(2),signingCredentials: creds);var jwtHandler = new JwtSecurityTokenHandler();var encodedJwt = jwtHandler.WriteToken(jwt);return encodedJwt;}/// <summary>/// 解析/// </summary>/// <param name="jwtStr"></param>/// <returns></returns>public static TokenModelJWT SerializeJWT(string jwtStr){var jwtHandler = new JwtSecurityTokenHandler();JwtSecurityToken jwtToken = jwtHandler.ReadJwtToken(jwtStr);object role = new object(); ;try{jwtToken.Payload.TryGetValue("Role", out role);}catch (Exception e){Console.WriteLine(e);throw;}var tm = new TokenModelJWT{Uid = Convert.ToInt32(jwtToken.Id),Role = role != null ? role.ToString() : "",};return tm;}}
}

View Code

JwtTokenAuth：

/// <summary>/// 中间件/// </summary>public class JwtTokenAuth{private readonly RequestDelegate _next;public JwtTokenAuth(RequestDelegate next){_next = next;}public Task Invoke(HttpContext httpContext){//检测是否包含'Authorization'请求头if (!httpContext.Request.Headers.ContainsKey("Authorization")){return _next(httpContext);}var tokenHeader = httpContext.Request.Headers["Authorization"].ToString();TokenModelJWT tm = JwtHelper.SerializeJWT(tokenHeader);//序列化token，获取授权//授权 注意这个可以添加多个角色声明，请注意这是一个 listvar claimList = new List<Claim>();var claim = new Claim(ClaimTypes.Role, tm.Role);claimList.Add(claim);var identity = new ClaimsIdentity(claimList);var principal = new ClaimsPrincipal(identity);httpContext.User = principal;return _next(httpContext);}}

View Code

startup的Configure中加入

//将TokenAuth注册中间件
app.UseMiddleware<JwtTokenAuth>();

接口加权限filter

启动调用会报错

是因为每次操作请求，都会经过TokenAuth 中的Invoke方法，方法中对Header信息进行过滤，因为现在Header中，并没有相应的配置信息，看到这里，你就想到了，这个特别像我们常见的[HttpGet]等特性，没错！在.Net Core 中，到处都可以看到AOP编程，真的特别强大。

这个时候我们就用到了最开始的那个权限按钮

新建一个LoginController，来模拟一次登陆操作，简单传递几个参数，将用户角色和缓存时间传递，然后生成Token，并生成到缓存中，为之后做准备。

 [Route("api/[controller]")]public class LoginController : Controller{/// <summary>/// 获取JWT的重写方法，推荐这种，注意在文件夹OverWrite下/// </summary>/// <param name="id">id</param>/// <param name="sub">角色</param>/// <returns></returns>
        [HttpGet][Route("Token2")]public JsonResult GetJWTStr(long id = 1, string sub = "Admin"){//这里就是用户登陆以后，通过数据库去调取数据，分配权限的操作TokenModelJWT tokenModel = new TokenModelJWT();tokenModel.Uid = id;tokenModel.Role = sub;string jwtStr = JwtHelper.IssueJWT(tokenModel);return Json(jwtStr);}}

调用获取tonken

复制到这里验证：

再次调用接口就可以了

示例代码：https://github.com/chuankang/DotNetCore/tree/master/OwnSpace/WebApiA

参考文档：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger

https://github.com/domaindrivendev/Swashbuckle.AspNetCore

转载于:https://www.cnblogs.com/chuankang/p/8783761.html