c#配置swagger文档

.net core6.0注入swagger，.net core 配置swagger文档
6.1号更新token验证

builder.Services.AddSwaggerGen(c =>
{
//添加token验证
c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Description = "请输入token,格式为 Bearer xxxxxxxx",
Name = "Authorization", //标头名
In = ParameterLocation.Header, //表示头部
Type = SecuritySchemeType.ApiKey,
BearerFormat = "JWT", //token
Scheme = "Bearer"
});
//添加验证条件
c.AddSecurityRequirement(new OpenApiSecurityRequirement {
{
new OpenApiSecurityScheme{
Reference =new OpenApiReference{
Type = ReferenceType.SecurityScheme,
Id ="Bearer"
}
},new string[]{ }//不设权限
}
});
c.SwaggerDoc("v1", new()
{
Title = builder.Environment.ApplicationName,//名字
Version = "v1",//版本
Description = $"会员管理接口平台",
});
var path = Path.Combine(AppContext.BaseDirectory, "DG.QIAN.Members.Api.xml"); // xml文档绝对路径,"API"为项目名
c.IncludeXmlComments(path, true); // true : 设置控制器层注释
c.OrderActionsBy(o => o.RelativePath); // 排序用的
});
添加划线代码即可添加待标头的请求，如

在里面填写对应的token值就行了

前言：虽然现在已经有.net8.0了，但是.net6因为已经出来两年了，所以更多公司在用，而且6.0和8.0的差别并不是很大，还是有一些可学的地方的，目前.net core 6.0的资料是最多的，所以搭建项目建议使用6.0会比较好

下面演示环境为visual studio2022+.net core webapi，其他项目也类似,讲的会比较细

在.net3.0之前创建项目会自动添加swagger管理，后面的更新之后需要手动开启openapi才会有支持：例如

#新建项目添加swagger

勾选openapi支持

直接运行，你会看到直接就能使用swagger，这是新建项目自带的

但是他不会有对方法的注释，需要添加一些注入，如：

图片中有详细的解释，一眼看过去会比较乱，仔细看所有的东西都在里面

代码：

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
//注入swagger
builder.Services.AddEndpointsApiExplorer();//生成文档
builder.Services.AddSwaggerGen(c =>//设置文档内容
{
c.SwaggerDoc("v1", new()
{
Title = builder.Environment.ApplicationName,//组名字，右上角可以选择
Version = "v1",//版本
Description = $"接口文档说明，放这里 ",
Contact = new OpenApiContact()
{
Name = "zhangsan",//名字
Email = "[email protected]",//邮箱
Url = null
}//通常这里都是放联系，地址的，一般不用
});
// xml文档绝对路径,"WebApplication2"为项目名，表示读取该项目的xml文件
var file = Path.Combine(AppContext.BaseDirectory, "WebApplication2.xml");
// xml文档绝对路径
var path = Path.Combine(AppContext.BaseDirectory, file);
// true : 设置控制器层注释，对控制器中方法的注释的显示
c.IncludeXmlComments(path, true);
// 对方法名的名称进行排序，首字母顺序。
c.OrderActionsBy(o => o.RelativePath);
});
var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())//只有当程序处于debug的情况才开启swagger
{
//分别注入中间件和ui中间间
app.UseSwagger();
//第一个为路径不能更改，第二个为版本可以更改
app.UseSwaggerUI(c => c.SwaggerEndpoint(
"/swagger/v1/swagger.json", $"{builder.Environment.ApplicationName} v1"));
}
app.UseAuthorization();

app.MapControllers();

app.Run();
将上面代码放进去会报错，因为我们设置了xml文档地址：开启方法》右键项目》属性》生成》输出》打开“生成包含api的文档的文件”

之后就可以直接运行了。

#在旧项目中添加swagger
还是以.ner core webapi举例，

在program中添加以下代码

//注入swagger
builder.Services.AddEndpointsApiExplorer();//生成文档
builder.Services.AddSwaggerGen(c =>//设置文档内容
{
c.SwaggerDoc("v1", new()
{
Title = builder.Environment.ApplicationName,//组名字，右上角可以选择
Version = "v1",//版本
Description = $"接口文档说明，放这里 ",
Contact = new OpenApiContact()
{
Name = "zhangsan",//名字
Email = "[email protected]",//邮箱
Url = null
}//通常这里都是放联系，地址的，一般不用
});
// xml文档绝对路径,"WebApplication2"为项目名，表示读取该项目的xml文件
var file = Path.Combine(AppContext.BaseDirectory, "WebApplication1.xml");
// xml文档绝对路径
var path = Path.Combine(AppContext.BaseDirectory, file);
// true : 设置控制器层注释，对控制器中方法的注释的显示
c.IncludeXmlComments(path, true);
// 对方法名的名称进行排序，首字母顺序。
c.OrderActionsBy(o => o.RelativePath);
});

if (app.Environment.IsDevelopment())//只有当程序处于debug的情况才开启swagger
{
//分别注入中间件和ui中间间
app.UseSwagger();
//第一个为路径不能更改，第二个为版本可以更改
app.UseSwaggerUI(c => c.SwaggerEndpoint(
"/swagger/v1/swagger.json", $"{builder.Environment.ApplicationName} v1"));
}
和上一个基本一致，注释都在代码中有写，在项目属性中开启“生成包含api文档的文件”，开启方法》右键项目》属性》生成》输出》打开“生成包含api的文档的文件”

然后在项目的nuget包中引用：Swashbuckle.AspNetCore，版本和环境版本一致即可。新建项目时如果选中openapi支持就会自动引用

x

注入之后就可以正常运行了，但是有一部分会报错，运行了，但是swagger不出现，只有控制台启动了。

有一个可能是，老项目的urls地址可能设置在appsettings.json文件中，如：

这里的urls设定了项目启动之后的指定地址，但是swagger注入是找的Properties文件下的launchSettings.json文件中指定的url地址，导致项目启动时找不到swagger.xml文件，所以不会启动浏览器生成swaggerUI了。（新建项目一般不会出现这个问题）

我们的项目地址应该在这里设置，其中以什么方式运行，这个就是基础了，试一下就知道了，

例如我们 使用默认容器运行，，

在profiles中设置，“launchUrl”应该为“swagger”，“applicationUrl”设置服务启动地址，如“http://localhost:5293”。对应以下》