.NET6之MiniAPI(十八)：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数据