MiniAPI（十八）：OpenAPI swagger

この記事からは、MiniAPIの使用を豊かにするための素晴らしいサードパーティ製のライブラリについて紹介します。
MiniAPIプロジェクトを作成する際に、テンプレートはOpenAPIを有効にするオプションを提供しており、このサードパーティ製ライブラリの優位性と強力さが窺えます。
![alt 画像](https://mmbiz.qpic.cn/mmbiz_png/4CAA63nvHRDK36tR1737OrHos9FWJpayXGzb380IoasrDG5z3gddHafsicaq1IPa8VhUl5BH1h5iaEoUD8vT8yKg/640?wx_fmt=png)
OpenAPIはAPIのテストに強力なサポートを提供し、APIを呼び出す開発者は容易にテストし、開発インターフェースとインターフェースパラメータを参照でき、大量のドキュメントの記述やデバッグプロセスの複雑さを効果的に節約できます。
より良い説明のために、注釈ファイルの生成機能を有効にする必要があります。プロジェクトファイルを開き、GenerateDocumentationFileノードを追加するだけです。
```XML
<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によるコードの導入を見てみましょう：
```CSharp
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>
    /// ID
    /// </summary>
    public int Id { get; set; }

    /// <summary>
    /// 名前
    /// </summary>
    public string Name { get; set; }
}
```
Tagsはall testで、同様の操作を一つのグループにまとめられ、swagger上で一つのグループに対応します。
![alt 画像](https://mmbiz.qpic.cn/mmbiz_png/4CAA63nvHRDK36tR1737OrHos9FWJpayqqOabtt602X1YicsJ6x9Y3Jo1Y0D5UQHeuExoaeFS6SERXdFPFVToTA/640?wx_fmt=png)
現在のMiniAPIは、個々のリクエストへの注釈のサポートはまだありません（get、post、put、deleteのapi注釈）、.NET 7で解決されることを期待しています。
リクエストメソッドが匿名メソッドである場合、パラメータも説明をサポートしていませんが、deleteリクエストのように名前付きメソッドであれば、メソッドのパラメータがswaggerに表示されます：
![alt 画像](https://mmbiz.qpic.cn/mmbiz_png/4CAA63nvHRDK36tR1737OrHos9FWJpayqxLmxuErfQO97sMCqrA1cmQWOcIpwCqUNaG46buletg0xcvo06qlgg/640?wx_fmt=png)
Mini APIがToken認証をサポートしている場合、AddSwaggerGenを使ってSecurityを追加し、Tokenを自動的に持つようにすることができます。具体的な方法はコード実装をご参照ください：c.AddSecurityDefinitionとc.AddSecurityRequirement。これにより、SwaggerページでAuthorizeボタンをクリックし、Tokenを入力すれば、すべてのリクエストにAuthorizationヘッダが自動的に追加されます。
![alt 画像](https://mmbiz.qpic.cn/mmbiz_png/4CAA63nvHRDK36tR1737OrHos9FWJpay8B5AuOMkcIR5Hr3vdPzah9rB5n9FkgqI0uexfoOAverQibEgMELojUQ/640?wx_fmt=png)
Getメソッドを呼び出すと、Authorizationが自動的に追加されます。
![alt 画像](https://mmbiz.qpic.cn/mmbiz_png/4CAA63nvHRDK36tR1737OrHos9FWJpayt90ibfnc3AkzCDKz10DUficiaWfvHvNiceibGEB5WqtXDAnq6KKsppBB71Q/640?wx_fmt=png)
バックエンドはTokenデータを取得します。
![alt 画像](https://mmbiz.qpic.cn/mmbiz_png/4CAA63nvHRDK36tR1737OrHos9FWJpayKN1LZiaYvhHc7p8Iic1ddSMrNYebgD4enhCQnPicZxyxfxjpoAomMuic0A/640?wx_fmt=png)

(Translated by GPT)

元のリンク：https://mp.weixin.qq.com/s?__biz=MzA3NDM1MzIyMQ==&mid=2247484960&idx=1&sn=07d3f7fa61e7481242092ec7b61221bc&chksm=9f00590aa877d01cb4edb7aff59c2abddecb4a1aa38b13dba289ff791a3a695c7de27ccb2063&token=877361727&lang=zh_CN#rd