c#配置swagger文档

dudke

已于 2024-02-28 16:56:53 修改

阅读量6.5k

点赞数 6

CC 4.0 BY-SA版权

文章标签： .netcore

于 2023-05-16 01:01:43 首次发布

本文链接：https://blog.csdn.net/qq_53217825/article/details/130695436

.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 = "xxx@qq.com",//邮箱
            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 = "xxx@qq.com",//邮箱
            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支持就会自动引用