Asp.net core WebApi 配置自定义swaggerUI和中文注释,Jwt Bearer配置

1.创建asp.net core webApi项目

默认会引入swagger的Nuget包

csharp 复制代码
  <PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />

2.配置基本信息和中文注释(默认是没有中文注释的)

2.1创建一个新的controller

csharp 复制代码
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

namespace webapi.Controllers
{
    /// <summary>
    /// 学生接口
    /// </summary>
    [Route("api/[controller]")]
    [ApiController]
    public class StudentController : ControllerBase
    {
        /// <summary>
        /// 获取学生列表
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public ActionResult GetList()
        {
            return Ok("学生列表");
        }

        /// <summary>
        ///根据Id查询
        /// </summary>
        /// <param name="Id">学生Id</param>
        /// <returns></returns>
        [HttpGet("{Id}")]
        public ActionResult GetById(int Id)
        {
            return Ok();
        }

        /// <summary>
        /// 获取token
        /// </summary>
        /// <param name="token"></param>
        /// <returns></returns>
        [HttpGet("{id}/{name}")]
        public string GetToken([FromHeader] string token)
        {
            return "123";
        }

        /// <summary>
        /// 添加学生信息
        /// </summary>
        /// <param name="stu">学生信息</param>
        /// <returns></returns>
        [HttpPost]
        public ActionResult Add([FromBody] StudentInfo stu)
        {
            return Ok();
        }

        /// <summary>
        /// 修改学生信息
        /// </summary>
        /// <param name="stu">学生信息</param>
        /// <param name="stu"></param>
        /// <returns></returns>
        [HttpPut]
        public ActionResult Update([FromBody] StudentInfo stu)
        {
            return Ok();
        }

        /// <summary>
        ///根据学生学号删除学生
        /// </summary>
        /// <param name="Id">学号</param>
        /// <returns></returns>
        [HttpDelete("{Id}")]
        public ActionResult DeletById(int Id)
        {
            return Ok();
        }
    }
}

2.2创建学生类

csharp 复制代码
namespace webapi
{
    /// <summary>
    ///学生表
    /// </summary>
    public class StudentInfo
    {
        /// <summary>
        ///学号
        /// </summary>
        public int Sno { get; set; }

        /// <summary>
        /// 姓名
        /// </summary>
        public string Name { get; set; }

        /// <summary>
        /// 年龄
        /// </summary>
        public int Age { get; set; }
    }
}

2.3 生成api中文注释xml(会把控制器上的方法和参数的中文注释生成xml文档)

选择项目-属性-生成-输出-勾选文档文件,xml文档文件路径可以默认

也可以直接双击项目,进入项目配置页面输入

csharp 复制代码
<GenerateDocumentationFile>True</GenerateDocumentationFile>
csharp 复制代码
 builder.Services.AddSwaggerGen(p =>
            {
                p.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo()
                {
                    Contact = new Microsoft.OpenApi.Models.OpenApiContact()
                    {
                        Email = "peng@g.com",
                        Name = "pzx",
                        Url = new Uri("http://www.baidu.com")
                    },
                    Description = "swagger设置基本信息",
                    Title = "webapi练习"
                });
                //加载api中文注释,true是加载控制器上的注释
                p.IncludeXmlComments(AppContext.BaseDirectory + Assembly.GetExecutingAssembly().GetName().Name + ".xml", true);
            });

运行项目-中文注释就出来了

3.默认的swaggerUI不是太好看我们可以使用自定义的UI

Nuget下载:IGeekFan.AspNetCore.Knife4jUI

csharp 复制代码
 <ItemGroup>
    <PackageReference Include="IGeekFan.AspNetCore.Knife4jUI" Version="0.0.13" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />
  </ItemGroup>

3.1配置使用Knife4jUI

csharp 复制代码
// Configure the HTTP request pipeline.
            if (app.Environment.IsDevelopment())
            {
                app.UseSwagger();
                app.UseSwaggerUI(p =>
                {
                    p.SwaggerEndpoint("/swagger/v1/swagger.json", "wepai");
                    p.RoutePrefix = "swagger";//设置前缀,默认swagger
                });
                //使用自定义UI
                app.UseKnife4UI(p =>
                {
                    p.SwaggerEndpoint("/swagger/v1/swagger.json", "wepai");
                    p.RoutePrefix = "";//设置前缀,默认swagger
                });
            }

swagger默认使用的swaggerUI,运行路径是

csharp 复制代码
http://localhost:5160/swagger/index.html

要使用Knife4jUI可以把默认的swaggerUI的配置注释掉,把自己路由前缀设置为swagger

如果两个ui都想保留,就把前缀设置未不同,我这swaggerUI的前缀是swagger,Knife4jUI的前缀是空字符串

项目运行选择UI可以在launchSettings.json文件配置 lauchUrl和自己设置的RoutePrefix 值保持一直就可以了。

运行看效果,比默认的ui看起来更加的整洁

4.swaggerUI 配置 Bearer认证

csharp 复制代码
   builder.Services.AddSwaggerGen(p =>
            {
                p.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo()
                {
                    Contact = new Microsoft.OpenApi.Models.OpenApiContact()
                    {
                        Email = "peng@g.com",
                        Name = "pzx",
                        Url = new Uri("http://www.baidu.com")
                    },
                    Description = "swagger设置基本信息",
                    Title = "webapi练习"
                });
                //Bearer 的scheme定义
                var securityScheme = new OpenApiSecurityScheme()
                {
                    Description = "JWT Authorization 头使用Bearer 体系方案. 例: \"Authorization: Bearer 你的token\"",
                    Name = "Authorization",
                    //参数添加在头部
                    In = ParameterLocation.Header,
                    //使用Authorize头部
                    Type = SecuritySchemeType.Http,
                    //内容为以 bearer开头
                    Scheme = JwtBearerDefaults.AuthenticationScheme,//加了这个就不需要 输入Bearer 空格了,只要输入token就可以了
                    BearerFormat = "JWT"
                };

                //把所有方法配置为增加bearer头部信息
                var securityRequirement = new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "JWT认证"
                }
            },
            new string[] {}
        }
    };

                //注册到swagger中
                p.AddSecurityDefinition("JWT认证", securityScheme);
                p.AddSecurityRequirement(securityRequirement);

                //加载api中文注释
                p.IncludeXmlComments(AppContext.BaseDirectory + Assembly.GetExecutingAssembly().GetName().Name + ".xml", true);
            });

效果如下

Knife4jUI加请求头就比较方便(直接添加就行了,不需要配置)

配置和生成jwt可以看我下面的文章
https://blog.csdn.net/qq_41942413/article/details/134680803?csdn_share_tail=%7B%22type%22%3A%22blog%22%2C%22rType%22%3A%22article%22%2C%22rId%22%3A%22134680803%22%2C%22source%22%3A%22qq_41942413%22%7D

相关推荐
咖啡Beans21 小时前
SpringBoot2.7集成Swagger3.0
java·swagger
靓仔建10 天前
Asp.net core用Swashbuckle.AspNetCore库出现错误信息:No operations defined in spec!
后端·asp.net·swagger
csdn_aspnet18 天前
使用 Entity Framework Code First 方法创建 ASP.NET Core 5.0 Web API
.netcore·webapi
whltaoin19 天前
Spring Boot Swagger3常用注解详解与实战
spring boot·注解·swagger
现在没有牛仔了2 个月前
SpringBoot项目集成Swagger指南
spring boot·后端·swagger
wstcl2 个月前
安卓app、微信小程序等访问多个api时等待提示调用与关闭问题
android·微信小程序·webapi
ggtc2 个月前
为workflow-core扩展外抛事件
c#·webapi·workflow-core
百锦再2 个月前
一文精通 Swagger 在 .NET 中的全方位配置与应用
后端·ui·.net·接口·配置·swagger·访问
杨DaB2 个月前
【SpringBoot】Swagger 接口工具
java·spring boot·后端·restful·swagger
lgx0406051122 个月前
基于.Net Framework4.5 Web API 引用Swagger
swagger·.net framework