OpenAPIドキュメントの生成
機械可読なAPI仕様を生成します。
「OpenAPIドキュメントの生成」はCoddyKit上の無料C# Academyレッスンです。 これはレッスン3/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはC# Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 C# Academyコースには全4レッスンが含まれています。
OpenAPI とは
OpenAPI は、HTTP API を機械可読な形式で記述する標準です。これを基に、ドキュメント、クライアント SDK、テストツールを生成できます。
.NET 9 には OpenAPI ドキュメント生成機能が組み込まれており、多くのアプリでは従来の Swashbuckle 依存関係に置き換えることができます。
// OpenAPI document = JSON describing paths, schemas, paramsMicrosoft.AspNetCore.OpenApi パッケージ
組み込みのサポートは Microsoft.AspNetCore.OpenApi に含まれています。.NET 9 のテンプレートでは、すでに参照されています。
dotnet add package Microsoft.AspNetCore.OpenApiAddOpenApi
サービス構成で AddOpenApi を使用して、ドキュメント生成機能を登録します。
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();MapOpenApi
MapOpenApi によって生成されたドキュメントをエンドポイントで公開します。既定では /openapi/v1.json で提供されます。
var app = builder.Build();
app.MapOpenApi(); // GET /openapi/v1.json
app.Run();開発環境に限定する
本番環境で API の公開範囲が漏れるのを防ぐため、ドキュメントを開発環境でのみ公開するのが一般的です。
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
}エンドポイントの説明
OpenAPI メタデータはコードから補完されます。Minimal API のエンドポイントでは、WithSummary、WithDescription、WithTags を使用します。
app.MapGet("/products/{id}", (int id) => Results.Ok())
.WithSummary("Get a product by id")
.WithDescription("Returns a single product or 404.")
.WithTags("Products");レスポンスのドキュメント化
レスポンスの型とステータスコードを宣言して、ドキュメントに正確に一覧表示されるようにします。
app.MapGet("/products/{id}", (int id) => Results.Ok())
.Produces<Product>(StatusCodes.Status200OK)
.Produces(StatusCodes.Status404NotFound);ドキュメントトランスフォーマー
AddOpenApi に渡すドキュメントトランスフォーマーを使用して、ドキュメント全体（タイトル、バージョン、サーバーなど）をカスタマイズします。
builder.Services.AddOpenApi(options =>
{
options.AddDocumentTransformer((doc, ctx, ct) =>
{
doc.Info.Title = "Catalog API";
doc.Info.Version = "1.0";
return Task.CompletedTask;
});
});オペレーショントランスフォーマー
オペレーショントランスフォーマーを使うと、個々のオペレーションを調整できます。たとえば、すべてのエンドポイントに共通のヘッダーパラメーターを追加できます。
options.AddOperationTransformer((operation, ctx, ct) =>
{
operation.Responses.TryAdd("500",
new OpenApiResponse { Description = "Server error" });
return Task.CompletedTask;
});UI の追加
組み込みの生成機能は JSON ドキュメントを生成しますが、UI は提供しません。Scalar や Swagger UI などのビューアーと組み合わせて使用します。
// dotnet add package Scalar.AspNetCore
app.MapOpenApi();
app.MapScalarApiReference(); // interactive docs at /scalar/v1ビルド時の生成
Microsoft.Extensions.ApiDescription.Server ツールを使用すると、実行中のサーバーなしでビルド中に OpenAPI ファイルを出力できます。CI でのクライアント生成に便利です。
// .csproj
// <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
// produces obj/<App>.json on build確認問題
.NET 9 の OpenAPI の基本を確認します。
まとめ
OpenAPI ドキュメントを生成しました。
AddOpenApi()で生成機能を登録し、MapOpenApi()で JSON を提供します。WithSummary、Produces、タグを使ってエンドポイントを補足します。- ドキュメントトランスフォーマーとオペレーショントランスフォーマーで出力をカスタマイズします。
- Scalar や Swagger UI と組み合わせて、インタラクティブな表示を実現します。
次は、バージョン管理された API のドキュメント化です。
よくある質問
「OpenAPIドキュメントの生成」レッスンは無料ですか？
はい。「OpenAPIドキュメントの生成」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、C# Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 C# Academyコースには全4レッスンが含まれています。
「OpenAPIドキュメントの生成」で何を学びますか？
機械可読なAPI仕様を生成します。 ブラウザで直接実行するハンズオンコードでC# Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
C# Academyを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのC# Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン3/4です。
「OpenAPIドキュメントの生成」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このC# Academyレッスンでコードを書いて実行できますか？
はい。すべてのC# Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。
このコースのすべてのレッスン
- APIバージョニング戦略
- Asp.Versioningの設定
- OpenAPIドキュメントの生成
- バージョン管理されたAPIのドキュメント化