在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; }
}
看看效果:
是不是比之前更人性化了?