.NET7 Preview4 之OpenAPI swagger改进

Posted 2022-09-09 teayear

在MiniAPI系列中，《.NET6之MiniAPI(十八)：OpenAPI swagger》介绍了swagger在MiniAPI框架中的使用，当时留下很多不足，随着.NET7 Preview4的推出，这方面得到了很大的改进，我还是使用“十八”这篇文章的案例。
如果想参看原来文章，见下面引用：
此次对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; 

当年在做go时，很羡慕它的时间有微秒，纳秒，在做性能优化时，能很小颗粒度的查看引入方法执行的时间，当时.net的DateTime只有毫秒（虽然也有别的办法获取）。现在，在最新的.NET7 Preview4中，DateTime也有微秒和纳秒了，倍感亲切。

纳秒在百位上，没有十位和个位，但这也说明.NET在进化，向高性能进化，在乎微秒和百位纳秒了（哈哈）。
下面是引入这两个时间单位的实现：

namespace System 
    public struct DateTime 
        public DateTime(int year, int month, int day, int hour, int minute, int second, int millisecond, int microsecond);
        public DateTime(int year, int month, int day, int hour, int minute, int second, int millisecond, int microsecond, System.DateTimeKind kind);
        public DateTime(int year, int month, int day, int hour, int minute, int second, int millisecond, int microsecond, System.Globalization.Calendar calendar);
        public int Microsecond  get; 
        public int Nanosecond  get; 
        public DateTime AddMicroseconds(double value);
    
    public struct DateTimeOffset 
        public DateTimeOffset(int year, int month, int day, int hour, int minute, int second, int millisecond, int microsecond, System.TimeSpan offset);
        public DateTimeOffset(int year, int month, int day, int hour, int minute, int second, int millisecond, int microsecond, System.TimeSpan offset, System.Globalization.Calendar calendar);
        public int Microsecond  get; 
        public int Nanosecond  get; 
        public DateTimeOffset AddMicroseconds(double microseconds);
    
    public struct TimeSpan 
        public const long TicksPerMicrosecond = 10L;
        public const long NanosecondsPerTick = 100L;
        public TimeSpan(int days, int hours, int minutes, int seconds, int milliseconds, int microseconds);
        public int Microseconds  get; 
        public int Nanoseconds  get; 
        public double TotalMicroseconds  get; 
        public double TotalNanoseconds  get; 
        public static TimeSpan FromMicroseconds(double microseconds);
    
    public struct TimeOnly 
        public TimeOnly(int day, int hour, int minute, int second, int millisecond, int microsecond);
        public int Microsecond  get; 
        public int Nanosecond  get; 
    

.NET Preview5中，给MiniAPI带来了一个参数绑定的功能，看到这个功能，我一下子就开心了，因为它提供了一个把松散的传入数据或注入功能耦合在一起的能力，并且可以根据自己的需求自由组合，结合上原来的Fromxxx(Name=“”)]使用，尤其和谐。

看一下下面的例子，如果每个请求都带有X-UUID，可以直接放在父类里，这样的组合是不是更加灵活多变。

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/test", ([AsParameters] Order order) =>

    order.Logger?.LogInformation(order.UUID);
);

app.Run();

class Header

    [FromHeader(Name = "X-UUID")]
    public string? UUID  get; set; 

class Order : Header

    [FromQuery(Name = "no")]
    public int OrderNo  get; set; 
    public ILogger<Order>? Logger  get; set; 

绑定的参数，不只是class，还可以是其他自定义类型。

结构

struct Order 

    [FromHeader(Name = "X-UUID")]
    public string? UUID  get; set; 
    [FromQuery(Name = "no")]
    public int OrderNo  get; set; 
    public ILogger<Order>? Logger  get; set; 

记录

record Order 

    [FromHeader(Name = "X-UUID")]
    public string? UUID  get; set; 
    [FromQuery(Name = "no")]
    public int OrderNo  get; set; 
    public ILogger<Order>? Logger  get; set; 

结构记录

record struct Order 

    [FromHeader(Name = "X-UUID")]
    public string? UUID  get; set; 
    [FromQuery(Name = "no")]
    public int OrderNo  get; set; 
    public ILogger<Order>? Logger  get; set; 

      虽然这只是.NET的一小步，但给开发人员带了一大步，使整个API开发体验得到了，特别对数据接收体验提升了一大截。