Swashbuckle.AspNetCore で Failed to load API definition に遭遇したら

開発中の Web API に後から Swashbuckle.AspNetCore を追加したはいいけど、いざ Swagger UI を表示してみたら「Failed to load API definition」というエラーになって API 一覧が見れない。こんな感じのやつ。

このエラーに遭遇したら、ググる前にまず swagger.json がちゃんと生成されているか確認すること。

今回の場合、/swagger/v1/swagger.json にアクセスしてみたら、スキーマ ID が重複しているのが原因だとわかった。 スキーマ ID はデフォルトだとクラス名が使われるので、名前空間を含めたクラス名をスキーマ ID に使うように、Startup 内で指定したら解決。

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Title = "My API",
        Version = "v1"
    });

    // スキーマ ID は名前空間含めたクラス名にする
    c.CustomSchemaIds(type => type.FullName);
});

何度もハマったので、忘れないようにメモを残して置く。