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

  看看效果:

.NET7 Preview4 之OpenAPI swagger改进_swagger改进

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

  想要更快更方便的了解相关知识,可以关注微信公众号

.NET7 Preview4 之OpenAPI swagger改进_.NET7 Preview4_02