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

相关推荐
现在没有牛仔了4 天前
SpringBoot项目集成Swagger指南
spring boot·后端·swagger
wstcl16 天前
安卓app、微信小程序等访问多个api时等待提示调用与关闭问题
android·微信小程序·webapi
ggtc16 天前
为workflow-core扩展外抛事件
c#·webapi·workflow-core
百锦再16 天前
一文精通 Swagger 在 .NET 中的全方位配置与应用
后端·ui·.net·接口·配置·swagger·访问
杨DaB19 天前
【SpringBoot】Swagger 接口工具
java·spring boot·后端·restful·swagger
lgx04060511224 天前
基于.Net Framework4.5 Web API 引用Swagger
swagger·.net framework
ChaITSimpleLove1 个月前
.NET9 使用 OData 协议项目实战
restful·asp.net core·webapi·仓储模式·开放数据协议·分层隔离·.net odata
IT之家1 个月前
swagger文档生成html静态文档
swagger·openapi·离线文档
小王子10241 个月前
Django集成Swagger全指南:两种实用方案详解
django·swagger·openapi
小王子10242 个月前
Django集成Swagger全指南:两种实现方案详解
django·swagger·openapi