.NET7 Preview4 之OpenAPI swagger改进

在MiniAPI系列中，《.NET6之MiniAPI(十八)：OpenAPI swagger》介绍了swagger在MiniAPI框架中的使用，当时留下很多不足，随着.NET7 Preview4的推出，这方面得到了很大的改进，我还是使用“十八”这篇文章的案例。

如果想参看原来文章，见下面引用：

《.NET6之MiniAPI(十八)：OpenAPI swagger》

桂素伟，公众号：桂迹.NET6之MiniAPI(十八)：OpenAPI swagger

此次对OpenAPI的提升主要是通过命名空间Microsoft.AspNetCore.OpenApi带来的。

新建API项目，选用minimal api模板，并带有OpenAPI，同时在Nuget升级Swashbuckle.AspNetCore为6.3.1以后的版本，核心代码如下：

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi.Models;


var builder = WebApplication.CreateBuilder(args);


builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{


    c.SwaggerDoc("v1",
       new OpenApiInfo
       {
           Title = "MiniAPI7_new04-V1",
           Version = "v1"
       }
    );
    //添加授权
    var schemeName = "Bearer";
    c.AddSecurityDefinition(schemeName, new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "请输入不带有Bearer的Token",
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        Scheme = schemeName.ToLowerInvariant(),
        BearerFormat = "JWT"
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference
                            {
                                Type = ReferenceType.SecurityScheme,
                                Id = schemeName
                            }
                        },
                        new string[0]
                    }
                });
});


var app = builder.Build();


if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.EnablePersistAuthorization();
    });
}
//增
app.MapPost("/test", Results<Ok<Data>, NotFound> (Data data) =>
{
    if (data != null)
    {
        data.ID = 101;
        return TypedResults.Ok(data);
    }
    else
    {
        return TypedResults.NotFound();
    }
})
.WithTags("all test")
.WithOpenApi(operation =>
{
    operation.Description = "这是一个神密的功能，用来实现添加";
    operation.Summary = "添加Data";
    operation.Parameters.Clear();


    operation.RequestBody = new OpenApiRequestBody
    {
        Description = "添加的数据实体",
        Required = true,
        Content = new Dictionary<string, OpenApiMediaType>
        {
            {
                "application/json", new OpenApiMediaType
                {
                    Schema = new OpenApiSchema
                    {
                        Type = "object",
                        Properties = new Dictionary<string, OpenApiSchema>
                        {
                            {"ID",new OpenApiSchema{ Type="integer" } },
                            {"Name",new OpenApiSchema{ Type="string" } },
                            {"Token",new OpenApiSchema{ Type="string" } }
                        },
                    },
                }
            }
        },


    };
    return operation;
});


//删
app.MapDelete("/test/{id}", Results<Ok, NotFound> (int? id) =>
{
    if (id.HasValue)
    {
        return TypedResults.Ok();
    }
    else
    {
        return TypedResults.NotFound();
    }
})
.WithTags("all test")
.WithOpenApi(operation =>
{
    operation.Description = "这是一个神密的功能，用来实现删除";
    operation.Summary = "按编号删除";
    operation.Parameters[0].Description = "编号";
    operation.Parameters[0].AllowEmptyValue = true;
    return operation;
});


//改
app.MapPut("/test", (Data data) =>
{
})
.WithTags("all test")
.WithOpenApi(operation =>
{
    operation.Description = "这是一个神密的功能，用来实现修改";
    operation.Summary = "修改Data";
    operation.Parameters.Clear();
    return operation;
});


//查
app.MapGet("/test/{id}", Results<Ok<Data>, NotFound> (HttpRequest request, int? id) =>
{
    if (id.HasValue)
    {
        return TypedResults.Ok(new Data() { ID = id.Value, Name = "测试", Token = request.Headers["Authorization"] });
    }
    else
    {
        return TypedResults.NotFound();
    }
})
.WithTags("all test")
.WithOpenApi(operation =>
 {
     operation.Description = "这是一个神密的功能，用来实现查询";
     operation.Summary = "按编号查询";
     operation.Parameters[0].Description = "编号";
     operation.Parameters[0].AllowEmptyValue = true;
     return operation;
 });


app.Run();
/// <summary>
/// 提交数据
/// </summary>
class Data
{
    /// <summary>
    /// 编号 
    /// </summary>
    public int ID { get; set; }
    /// <summary>
    /// 名称
    /// </summary>
    public string? Name { get; set; }


    /// <summary>
    /// Token
    /// </summary>
    public string? Token { get; set; }
}

看看效果：

是不是比之前更人性化了？