Swagger/OpenAPI を使用する ASP.NET Core Web API のドキュメント

作成者: Christoph Nienaber および Rico Suter

Swagger (OpenAPI) は REST API を記述するための仕様であり、言語に依存しません。 これにより、コンピューターと人間の両方が、ソース コードに直接アクセスせずに REST API の機能を理解できるようになります。 主な目的は次のとおりです。

• 関連のないサービスに接続するために必要な作業量を最小限にします。
• 正確にサービスをドキュメント化するために必要な時間を減らします。

.NET 用の 2 つの主要な OpenAPI の実装は、Swashbuckle と NSwag です。次を参照してください。

• Swashbuckle の概要
• NSwag の概要

OpenAPI と Swagger

Swagger プロジェクトは 2015 年に OpenAPI Initiative に寄贈され、それ以降は OpenAPI と呼ばれています。 どちらの名前も同じように使用されます。 ただし、"OpenAPI" は仕様を指します。 "Swagger" は、オープンソース製品および OpenAPI Specification と協力している SmartBear による商用製品のファミリを指します。 OpenAPIGenerator などの後続のオープンソース製品も Swagger ファミリ名に該当しますが、SmartBear からはリリースされていません。

要約すると、次のようになります。

• OpenAPI は仕様です。
• Swagger は、OpenAPI 仕様を使用するツールです。 たとえば、OpenAPIGenerator や SwaggerUI などです。

OpenAPI 仕様 (openapi.json)

OpenAPI の仕様は、API の機能について説明されているドキュメントです。 そのドキュメントは、コントローラーとモデル内の XML および属性の注釈に基づいています。 それは OpenAPI フローの中核部分であり、SwaggerUI などのツールを駆動するために使用されます。 規定では、openapi.json という名前です。 簡略化された OpenAPI の仕様の例は次のとおりです。

{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        …
      }
    },
    "/api/Todo/{id}": {
      "get": {
        …
      },
      "put": {
        …
      },
      "delete": {
        …
      }
    }
  },
  "components": {
    "schemas": {
      "ToDoItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "isCompleted": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

Swagger UI

Swagger UI には、生成された OpenAPI の仕様を使用してサービスに関する情報が提供される Web ベースの UI が用意されています。 ミドルウェアの登録呼び出しを使用して ASP.NET Core アプリでホストすることができるように、Swashbuckle と NSwag の両方に埋め込みバージョンの Swagger UI が含まれます。 Web UI は次のようになります。

コントローラー内の各パブリック アクション メソッドを UI からテストすることができます。 メソッドの名前を選択してセクションを展開します。 必要なパラメーターを追加し、 [Try it out!](試してみる) を選択します。

Note

スクリーンショットに使用される Swagger UI バージョンは、バージョン 2 です。 バージョン 3 の例については、Petstore の例に関するページを参照してください。

Swagger UI エンドポイントのセキュリティ保護

Swagger UI エンドポイントをセキュリティで保護するには MapSwagger().RequireAuthorization を呼び出します。 次の例では、swagger エンドポイントをセキュリティで保護します:

using System.Security.Claims;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();

var app = builder.Build();

  if (app.Environment.IsDevelopment())
  {
    app.UseSwagger();
    app.UseSwaggerUI();
  }

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapSwagger().RequireAuthorization();

app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
    .RequireAuthorization();

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

上記のコードでは、/weatherforecast エンドポイントは承認を必要としませんが、Swagger エンドポイントは承認を必要とします。

次の Curl は、Swagger UI エンドポイントをテストするために JWT トークンを渡します:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json

JWT トークンを使用したテストの詳細については、「dotnet user-jwts を使用したトークンの生成」 を参照してください。

コンパイル時に XML ドキュメント ファイルを生成します。

詳細については、「GenerateDocumentationFile」を参照してください。

次のステップ

• Swashbuckle の概要
• NSWag の概要