.NET6之Mini API【十八、OpenAPI swagger】

从本篇开始,介绍一些很不错的三方库,来丰富MiniAPI的使用。

在创建MiniAPI项目时,模板提供了一个是否启用OpenAPI的选项,足见这个三方库的优势和强大。

OpenAPI为我们测试API提供了强大的支持,调用API的开发人员,可以轻松测试,参照开发接口和接口参数,有效的节省了大量文档的书写和调试流程复杂性。

为了更好的说明,需要开启注释文件生成功能,打开项目文件,增加

GenerateDocumentdationFile节点即可。

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <GenerateDocumentationFile>True</GenerateDocumentationFile>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />
  </ItemGroup>
</Project>

先看Swagger引入的代码:

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
       new OpenApiInfo
       {
           Title = "MiniAPI08-V1",
           Version = "v1"
       }
    );
    //设置xml引用
    var filePath = Path.Combine(System.AppContext.BaseDirectory, "MiniAPI08.xml");
    c.IncludeXmlComments(filePath);

    //添加授权
    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.MapPut("/test", (Data data) =>
{
})
.WithName("puttest")
.WithTags("all test");

app.MapDelete("/test/{id}", TestHandle.DeleteTest)
.WithName("deletetest")
.WithTags("all test");

app.MapGet("/test/{id}", (HttpRequest request, int id) =>
{
    Console.WriteLine(request.Headers["Authorization"]);
})
.WithName("gettest")
.WithTags("all test")
.Produces<Data>(StatusCodes.Status200OK)
.Produces(StatusCodes.Status404NotFound);

app.MapPost("/test", (Data data) =>
 {
 })
.WithName("posttest")
.WithTags("all test");

app.Run();

class TestHandle
{
    /// <summary>
    /// 删除Test
    /// </summary>
    /// <param name="id">Data的主键</param>
    /// <returns></returns>
    public static bool DeleteTest(int id)
    {
        return true;
    }
}
/// <summary>
/// 提交数据
/// </summary>
class Data
{
    /// <summary>
    /// 编号 
    /// </summary>
    public int Id { get; set; }
    /// <summary>
    /// 名称
    /// </summary>
    public string Name { get; set; }
}

Tags 是all test,可以把同类操作放在一个组里,对应着swagger的一组

现在的MiniAPI对单个请求还不支持注释(就是get ,post,put,delete的api注释),相信.NET 7会解决掉。

如果请求的方法是匿名方法,同样参数也是不支持说明的,如果像delete请求,指像命名方法,方法的参数是注释说明是会显示在swagger里的:

如查Mini API支持Token验证,可以通过AddSwaggerGen添加Security来实现自带Token,具体做法见代码实现:c.AddSecurityDefinition和 c.AddSecurityRequirement。这样可以在Swagger页面,点击Authorize按钮,输入Token,这时,所有的请求都会带上Authorization的header。

调用Get方法时,会自动带上Authorization

后端会获取到Token数据

全部.NET6之MiniAPIPDF版本下载地址 https://club.51aspx.com/circle/10569.html

给TA打赏
共{{data.count}}人
人已打赏
.NET

.NET6之Mini API【十七、缓存】

2022-7-6 11:32:11

.NET

记一次 .NET 差旅管理后台 CPU 爆高分析

2022-7-6 17:09:08

0 条回复 A文章作者 M管理员
    暂无讨论,说说你的看法吧
个人中心
今日签到
有新私信 私信列表
搜索