OpenAPI ドキュメントを使用する

ローカルのアドホック テストに Swagger UI を使用する

既定では、Microsoft.AspNetCore.OpenApi パッケージには、OpenAPI ドキュメントを視覚化または操作するための組み込みサポートは付属していません。 OpenAPI ドキュメントを視覚化または操作するための一般的なツールとして、Swagger UI と ReDoc があります。 Swagger UI と ReDoc は、いくつかの方法でアプリに統合できます。 Visual Studio や Visual Studio Code などのエディターには、OpenAPI ドキュメントに対するテスト用の拡張機能と組み込みのエクスペリエンスが用意されています。

Swashbuckle.AspNetCore.SwaggerUi パッケージには、アプリで使用するための Swagger UI の Web アセットのバンドルが用意されています。 このパッケージを使用して、生成されたドキュメントの UI をレンダリングできます。 これを構成するには、次のようにします。

• Swashbuckle.AspNetCore.SwaggerUi パッケージをインストールします。
• 先ほど登録した OpenAPI ルートを参照して swagger-ui ミドルウェアを有効にします。

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });

}

app.MapGet("/", () => "Hello world!");

app.Run();

情報漏えいを制限するセキュリティのベスト プラクティスとして、 OpenAPI ユーザー インターフェイス (Swagger UI、ReDoc、Scalar) は開発環境でのみ有効にする必要があります。 たとえば、 Swagger OAuth 2.0 の構成を参照してください。

アプリを起動し、 https://localhost:<port>/swagger に移動して Swagger UI を表示します。

https プロファイルを使用して、Properties/launchSettings.json の Swagger UI URL でアプリを自動で起動するには:

• launchBrowserが有効になっていることを確認します (true)。
• launchUrl を swagger に設定します。

"launchBrowser": true,
"launchUrl": "swagger",

対話型 API ドキュメントに Scalar を使用する

Scalar は、OpenAPI 用のオープンソースの対話型ドキュメント UI です。 Scalar は、ASP.NET Core によって提供される OpenAPI エンドポイントと統合できます。 Scalar を構成するには、Scalar.AspNetCore パッケージをインストールします。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.MapGet("/", () => "Hello world!");

app.Run();

アプリを起動し、https://localhost:<port>/scalar に移動してスカラー UI を表示します。

httpsのProperties/launchSettings.json プロファイルを使用して、スカラー UI URL でアプリを自動的に起動するには:

• launchBrowserが有効になっていることを確認します (true)。
• launchUrl を scalar に設定します。

"launchBrowser": true,
"launchUrl": "scalar",

Spectral を使用して生成された OpenAPI ドキュメントを検証する

Spectral は、オープンソースの OpenAPI ドキュメント リンターです。 Spectral をアプリ ビルドに組み込んで、生成された OpenAPI ドキュメントの品質を検証できます。 パッケージのインストール手順に従って Spectral をインストールしてください。

ビルド時に OpenAPI ドキュメントを linting するためにスペクトラルを利用するには、最初に Microsoft.Extensions.ApiDescription.Server パッケージをインストールして、ビルド時の OpenAPI ドキュメントの生成を有効にします。

アプリの .csproj ファイルで次のプロパティを設定して、ビルド時のドキュメント生成を有効にします。

<PropertyGroup>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>

dotnet build を実行して、ドキュメントを生成します。

dotnet build

次の内容を持つ新しいファイル .spectral.yml を作成します。

extends: ["spectral:oas"]

生成されたファイルで spectral lint を実行します。

spectral lint WebMinOpenApi.json
...

The output shows any issues with the OpenAPI document. For example:

```output
1:1  warning  oas3-api-servers       OpenAPI "servers" must be present and non-empty array.
3:10  warning  info-contact           Info object must have "contact" object.                        info
3:10  warning  info-description       Info "description" must be present and non-empty string.       info
9:13  warning  operation-description  Operation "description" must be present and non-empty string.  paths./.get
9:13  warning  operation-operationId  Operation must have "operationId".                             paths./.get

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)

挿入のサポート IOpenApiDocumentProvider

依存関係の挿入を通じてサービスに IOpenApiDocumentProvider を挿入して、HTTP 要求コンテキストの外部であっても、プログラムで OpenAPI ドキュメントにアクセスできます。

public class DocumentService
{
    private readonly IOpenApiDocumentProvider _documentProvider;

    public DocumentService(IOpenApiDocumentProvider documentProvider)
    {
        _documentProvider = documentProvider;
    }

    public async Task<OpenApiDocument> GetApiDocumentAsync()
    {
        return await _documentProvider.GetOpenApiDocumentAsync("v1");
    }
}

DI コンテナーにサービスを登録します。

builder.Services.AddScoped<DocumentService>();

これにより、クライアント SDK の生成、バックグラウンド プロセスでの API コントラクトの検証、外部システムへのドキュメントのエクスポートなどのシナリオが可能になります。

IOpenApiDocumentProviderの挿入のサポートは、.NET 10 の ASP.NET Core で導入されました。 詳細については、 dotnet/aspnetcore #61463 を参照してください。