OpenAPI ドキュメントを使用する
ローカルのアドホック テストに Swagger UI を使用する
既定では、Microsoft.AspNetCore.OpenApi パッケージには、OpenAPI ドキュメントを視覚化または操作するための組み込みサポートは付属していません。 OpenAPI ドキュメントを視覚化または操作するための一般的なツールとして、Swagger UI と ReDoc があります。 Swagger UI と ReDoc は、いくつかの方法でアプリに統合できます。 Visual Studio や VS Code などのエディターには、OpenAPI ドキュメントに対するテスト用の拡張機能と組み込みのエクスペリエンスが用意されています。
Swashbuckle.AspNetCore.SwaggerUi パッケージには、アプリで使用するための Swagger UI の Web アセットのバンドルが用意されています。 このパッケージを使用して、生成されたドキュメントの UI をレンダリングできます。 これを構成するには、次のようにします。
Swashbuckle.AspNetCore.SwaggerUiパッケージをインストールします。- 先ほど登録した OpenAPI ルートを参照して swagger-ui ミドルウェアを有効にします。
- 情報漏えいとセキュリティの脆弱性を制限するために、"開発環境でのみ 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();
app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/openapi/v1.json", "v1");
});
}
app.MapGet("/", () => "Hello world!");
app.Run();
対話型 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();
app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
app.MapScalarApiReference();
}
app.MapGet("/", () => "Hello world!");
app.Run();
生成された OpenAPI ドキュメントの Spectral によるリンティング
Spectral は、オープンソースの OpenAPI ドキュメント リンターです。 Spectral をアプリ ビルドに組み込んで、生成された OpenAPI ドキュメントの品質を検証できます。 パッケージのインストール手順に従って Spectral をインストールしてください。
Spectral を利用するには、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)
.NET 6、7、または 8 で生成された OpenAPI ドキュメントを最小限の API で使用する方法については、「Swagger と NSwag の概要」をご覧ください。
ASP.NET Core