C#のASP.NETでSwaggerを使ってAPIドキュメントを自動生成する方法！初心者向け完全解説ガイド
生徒
「C#を使ってWebアプリの開発に挑戦しているのですが、作った機能の一覧や使い方の説明書を準備するのが大変です。何か自動で作成してくれる便利な仕組みはありませんか？」
先生
「それなら、ASP.NETという仕組みに備わっているSwaggerという機能を使うのがおすすめです。これを使うと、プログラムの内容から自動的にとても見やすい説明書画面を作ってくれますよ。」
生徒
「自動で作ってくれるなんて最高ですね！パソコンの操作にあまり慣れていない私でも簡単に設定して使うことができますか？」
先生
「はい、大丈夫です。基本的な設定手順から実際の画面の使い方まで、分かりやすく順番に解説していきますね。それでは、具体的な方法を一緒に見ていきましょう！」
1. APIドキュメントとSwaggerの基本を学ぼう
まずは、今回登場する重要な言葉の意味から確認していきましょう。プログラミングの学習では、カタカナの専門用語がたくさん出てきますが、一つひとつイメージで捉えると難しくありません。
API（エーピーアイ）とは、アプリケーション・プログラミング・インターフェースの略称です。これは、インターネットを通じて「特定のデータを頂戴」とお願いされたときに、「はい、どうぞ」とデータを返却する、窓口のような仕組みのことです。例えば、スマートフォンの天気予報アプリが、気象庁のサーバーから最新の天気の情報を取得するときなどに使われています。
そして、APIドキュメントとは、その窓口の「利用説明書」のことです。この窓口を利用するためには、どのような形式でお願いをすればいいのか、どのようなデータが返ってくるのかを詳しく書き記した書類が必要になります。これを手作業で書くと大変なので、自動化してくれるのがSwagger（スワッガー）という仕組みです。これを使うことで、プログラムのソースコードを読み取って、ウェブブラウザで確認できるきれいな説明書画面を自動的に作成してくれます。
2. ASP.NETとWebアプリ開発の全体像
C#というプログラミング言語を使ってウェブアプリケーションを開発するときに、最もよく使われる土台となる仕組みがASP.NET（エーエスピー・ドットネット）です。これを使うことで、世界中の人々がブラウザ経由でアクセスできる高機能なシステムを効率よく作ることができます。
初心者の段階では、パソコンの中でプログラムがどのように動いているのか想像しにくいかもしれません。ウェブアプリ開発では、画面を表示するためのデータを準備する役割を持つプログラムのことをWeb API（ウェブ・エーピーアイ）と呼びます。このWeb APIを作成した際、どのような機能が含まれているのかを一覧で確認できる状態にしておくことが、共同で作業をする他の開発者にとっても、自分自身にとっても非常に重要になります。Swaggerを導入すると、特別な書類を準備しなくても、プログラムを実行するだけで最新の説明書が画面に表示されるようになります。
3. 開発環境の準備とプロジェクトの作成手順
それでは、実際にC#のプログラムを動かすための準備を説明します。プログラムを書くためには、統合開発環境と呼ばれる専用のソフトウェアであるVisual Studio（ビジュアル・スタジオ）などのツールを使用します。
パソコンの操作に不慣れな方でも、以下の手順に沿って操作すれば簡単にプロジェクトと呼ばれる作業用のフォルダ一式を作ることができます。まずはツールを起動し、「新しいプロジェクトの作成」を選択します。そこで「ASP.NET Core Web API」という種類のテンプレートを探して選択してください。プロジェクトの名前を分かりやすい英数字で入力し、次へ進みます。最近のバージョンでは、最初から「OpenAPIサポートを有効にする」というチェックボックスが用意されていることが多く、ここにチェックを入れておくだけで、自動的にSwaggerを使う準備が整うようになっています。
4. 最もシンプルなWeb APIのプログラムコード
プロジェクトが作成できたら、まずはデータを返却する最も簡単なプログラムの例を見てみましょう。ここでは、アクセスすると挨拶の言葉を返してくれる単純な窓口を作ります。
以下のコードは、コントローラーと呼ばれる、リクエストを受け付ける役割を持つ部品です。このプログラムを動かすことで、外部からの呼び出しを待ち受ける状態を作ることができます。
using Microsoft.AspNetCore.Mvc;
namespace MyFirstApi.Controllers
{
[ApiController]
[Route("api/[controller]")]
public class HelloController : ControllerBase
{
[HttpGet]
public string GetGreeting()
{
return "こんにちは！初めてのAPIドキュメント自動生成へようこそ！";
}
}
}
このコードの中にある[HttpGet]というのは、ブラウザでホームページを開くときと同じような方法でデータを取得しにいくことを意味しています。プログラムを実行すると、この窓口が自動的に認識され、説明書の対象となります。
5. 計算を実行して結果を返すAPIプログラム
次に、もう少しプログラミングらしい動きをする窓口を追加してみましょう。二つの数字を受け取って、その合計の計算結果を算出して戻すという機能です。
このようなプログラムを追加したとき、手動の説明書であれば「引数に数字を入れてください」といった追記が必要になりますが、Swaggerであればコードを書き換えるだけで自動的に追記してくれます。次のコードを追加してみます。
using Microsoft.AspNetCore.Mvc;
namespace MyFirstApi.Controllers
{
[ApiController]
[Route("api/[controller]")]
public class CalcController : ControllerBase
{
[HttpGet("add")]
public int AddNumbers(int first, int second)
{
int total = first + second;
return total;
}
}
}
このプログラムでは、firstとsecondという二つの変数に数字を受け取り、それを足し算した結果を画面に返す処理を行っています。プログラムが完成したら、次にこれを動かすための設定ファイルを確認します。
6. 起動時の設定ファイルでSwaggerを有効化する方法
作成したプログラムを動かし、自動的に説明書画面を表示させるためには、プログラムの起動時に「Swaggerの機能を使います」という宣言をしておく必要があります。これを行うのが、プロジェクト内にあるProgram.csという名前のファイルです。
このファイルは、アプリが立ち上がるときに一番最初に読み込まれる設定の設計図のようなものです。一般的な設定内容を以下に提示します。初心者の方は、このような呪文のようなコードが最初に用意されていると覚えておけば問題ありません。
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();
この中のAddSwaggerGenという命令が、ドキュメントを生成する機能をアプリに組み込む設定で、UseSwaggerUIという命令が、ウェブブラウザで見られる専用の画面を表示するための設定です。これらが揃うことで、準備が完了します。
7. ユーザーの情報を登録する擬似的なAPIプログラム
データの取得だけでなく、新しく情報を登録するような窓口の例も見ておきましょう。今度は、ユーザーの名前と識別番号をセットにして送信してもらい、正しく受け取ったことを通知するプログラムです。
このように少しデータ構造が複雑になった場合でも、Swaggerは送信すべきデータの形を解析して、見やすい一覧にしてくれます。以下のコードを使って、その仕組みを表現します。
using Microsoft.AspNetCore.Mvc;
namespace MyFirstApi.Controllers
{
public class UserData
{
public int Id { get; set; }
public string Name { get; set; } = string.Empty;
}
[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
[HttpPost]
public string CreateUser(UserData user)
{
return $"識別番号 {user.Id} の {user.Name} 先生を新しく登録しました！";
}
}
}
このコードでは、[HttpPost]という命令を使っています。これは、新しいデータを登録したり、送信したりするときによく使われる窓口の形式です。これで合計三つの異なる機能がプログラム内に出来上がりました。
8. 実際にプログラムを実行してドキュメントを確認する
それでは、準備したプログラムを実行してみましょう。Visual Studioの上部にある再生ボタンのような「デバッグ開始」のボタンをクリックします。すると、黒い画面のウィンドウが立ち上がった後に、自動的にウェブブラウザが起動します。
ブラウザのアドレス欄に表示されているURLの末尾に/swaggerと入力してエンターキーを押すと、カラフルで非常に洗練された画面が表示されます。これがSwaggerによって自動生成されたAPIドキュメントの画面です。画面上には、先ほど作成した三つのコントローラーの名前が並んでおり、それぞれの窓口がどのような名前で、どのようなデータを求めているのかが一目で把握できるようになっています。手動で文字を入力して書類を作らなくても、プログラムコードからこれだけの情報が綺麗に整理されて出力されます。
9. 自動生成された画面上でテスト実行を行う方法
Swaggerの素晴らしいところは、単に説明書を表示するだけでなく、その画面上で実際にプログラムの動作テストができる点にあります。これを使って、先ほど作成した計算プログラムを動かしてみましょう。
画面に表示されている計算用の項目をクリックして開くと、右側に「Try it out（試してみる）」というボタンが表示されます。これをつつくと、入力欄に数字を打ち込めるようになります。例えば、最初の欄に十、二番目の欄に二十と入力して、その下にある青い「Execute（実行）」ボタンを押します。すると、即座にプログラムにデータが送られ、計算された結果が画面に返ってきます。実際の表示結果のイメージは以下のようになります。
ResponseBody
30
このように、難しいコマンドを入力することなく、マウス操作と簡単な文字入力だけで、自分の作ったプログラムが正しく動いているかを確認できるため、開発の効率が劇的に向上します。
