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