【Core Swagger】.NET Core中使用swagger

时间  2019-11-29 标签 Core Swagger core 使用 swagger

 一.入门

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

 

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

 

2.startup中配置：github

ConfigureServices中：web

           //注册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的生成地址和文件名，须要在项目的属性中进行配置，右键项目-> 属性-> 生成 以下图：json

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

 

 

 

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 swagger
            services.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路径区分大小写，这里用appcontext
                string xmlPath = Path.Combine(basePath, "WebApiA.xml");
                //若是有xml注释文档就读取，需在项目属性生成xml
                if (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());
            });
            #endregion


            services.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()),//Id
                new 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，获取受权

            //受权 注意这个能够添加多个角色声明，请注意这是一个 list
            var 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

                




                

            

        

    










    

        联系我们
        沪ICP备13005482号-10