.NET7 Preview4 之OpenAPI swagger改进

Posted 2022-05-19 dotNET跨平台

在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; 

看看效果：

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