.NET WebAPIプロジェクトにおいてSwaggerを導入する際には、いくつかの課題に直面することがあります。本稿では、実際のプロジェクトで筆者が遇到了した問題とその解決策について詳しく解説いたします。

プロジェクトの準備

まず最初に、新しいWebAPIプロジェクトを作成します。Visual StudioのテンプレートからWeb APIを選択することで、基本的なプロジェクト構造が自動的に生成されます。

デフォルトの状態では、API一覧画面やGETメソッドのテスト画面が表示されますが、見た目の面ではやや物足りない印象があります。また、APIのテスト機能も限定的であるため、実際の開発においては不便さを感じることがあります。

Swaggerパッケージのインストール

Swaggerを導入するには、NuGetパッケージマネージャーからSwashbuckleをインストールするのが一般的です。このパッケージをインストールすることで、APIのドキュメント自動生成とテスト用UIの両方を利用できるようになります。

インストールが完了したら、早速実行してみましょう。多くの場合、特に設定を行わなくても基本的な機能は動作します。

発生する可能性のある問題

問題1: XMLドキュメント関連のエラー

実行時にXMLドキュメント関連のエラーが発生する場合があります。この問題は、プロジェクトの設定でXMLドキュメントファイルの生成を有効にすることで解決できます。

ソリューションエクスプローラーでプロジェクトを右クリックし、プロパティを開きます。次に「ビルド」タブを選択し、「XMLドキュメントファイル」にチェックを入れます。これにより、ビルド時にXMLドキュメントが生成され、Swaggerが正しく動作ようになります。

問題2: アセンブリ参照のエラー

有时候会遇到程序集版本不匹配导致的异常。这是因为项目中引用的DLL文件版本与Swagger所需的版本不一致。为了解决这个问题，需要在web.config文件中添加以下绑定重定向配置：

<dependentAssembly>
    <assemblyIdentity name="System.Net.Http.Formatting" publicKeyToken="31bf3856ad364e35" culture="neutral" />
    <bindingRedirect oldVersion="0.0.0.0-5.0.0.0" newVersion="5.0.0.0" />
</dependentAssembly>
<dependentAssembly>
    <assemblyIdentity name="System.Web.Http" publicKeyToken="31bf3856ad364e35" culture="neutral" />
    <bindingRedirect oldVersion="0.0.0.0-5.0.0.0" newVersion="5.0.0.0" />
</dependentAssembly>
<dependentAssembly>
    <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
    <bindingRedirect oldVersion="0.0.0.0-8.0.0.0" newVersion="8.0.0.0" />
</dependentAssembly>

此外，如果在Swagger的Nancy版本中遇到兼容性问题，可能还需要对相关代码进行注释处理。这通常是因为NuGet包更新滞后导致的临时性问题です。

Swaggerの動作確認

以上の設定が完了したら、アプリケーションを実行し、ブラウザで以下のURLにアクセスします：

http://localhost:28129/swagger

自動的にSwagger UIの画面に切り替わり、APIの一覧が表示されます。これで基本的な設定は完了です。

サンプルモデルの作成

実際のAPI開発では、JSON形式でのデータ受け渡しが一般的になります。ここでは、サンプルとしてアプリケーション情報を管理するためのモデルクラスを作成します。

/// <summary>
/// アプリケーション情報
/// </summary>
public class ApplicationInfo
{
    /// <summary>
    /// アプリケーションID
    /// </summary>
    public int Id { get; set; }
    
    /// <summary>
    /// アプリケーション名
    /// </summary>
    public string Name { get; set; }
    
    /// <summary>
    /// 備考
    /// </summary>
    public string Description { get; set; }
}

また、APIの処理結果を返すためのレスポンスモデルも作成しておきます。

/// <summary>
/// API処理結果
/// </summary>
public class ApiResponse
{
    /// <summary>
    /// 結果コード
    /// </summary>
    public int StatusCode { get; set; }
    
    /// <summary>
    /// 結果メッセージ
    /// </summary>
    public string Message { get; set; }
}

JSON変換ヘルパークラスの実装

HttpResponseMessageでJSONデータを返すためのヘルパークラスを作成します。

public class JsonHelper
{
    public static HttpResponseMessage ToJson(object data)
    {
        var serializer = new JavaScriptSerializer();
        var json = serializer.Serialize(data);
        
        return new HttpResponseMessage(HttpStatusCode.OK)
        {
            Content = new StringContent(json, Encoding.UTF8, "application/json")
        };
    }
    
    public static HttpResponseMessage ToJson(IEnumerable<object> dataList)
    {
        var serializer = new JavaScriptSerializer();
        var json = serializer.Serialize(dataList);
        
        return new HttpResponseMessage(HttpStatusCode.OK)
        {
            Content = new StringContent(json, Encoding.UTF8, "application/json")
        };
    }
}

APIコントローラーの作成

CRUD操作を持つAPIコントローラーを見てみましょう。

public class ApplicationController : ApiController
{
    private List<ApplicationInfo> FetchAll()
    {
        var items = new List<ApplicationInfo>();
        items.Add(new ApplicationInfo { Id = 1, Name = "LINE", Description = "メッセージングアプリ" });
        items.Add(new ApplicationInfo { Id = 2, Name = "Instagram", Description = "写真共有SNS" });
        items.Add(new ApplicationInfo { Id = 3, Name = "Gmail", Description = "メールサービス" });
        items.Add(new ApplicationInfo { Id = 4, Name = "Slack", Description = "ビジネスチャット" });
        return items;
    }

    /// <summary>
    /// 全アプリケーション一覧を取得
    /// </summary>
    [HttpGet]
    public HttpResponseMessage GetAll()
    {
        return JsonHelper.ToJson(FetchAll());
    }

    /// <summary>
    /// 指定されたアプリケーションを取得
    /// </summary>
    [HttpGet]
    public HttpResponseMessage GetById(int id)
    {
        var item = FetchAll().FirstOrDefault(x => x.Id == id);
        return JsonHelper.ToJson(item);
    }

    /// <summary>
    /// 新規アプリケーションを追加
    /// </summary>
    [HttpPost]
    public HttpResponseMessage Create([FromBody]ApplicationInfo model)
    {
        var response = new ApiResponse { StatusCode = 200, Message = "正常に登録されました" };
        return JsonHelper.ToJson(response);
    }

    /// <summary>
    /// アプリケーション情報を更新
    /// </summary>
    [HttpPut]
    public HttpResponseMessage Modify([FromBody]ApplicationInfo model)
    {
        var response = new ApiResponse { StatusCode = 200, Message = "正常に更新されました" };
        return JsonHelper.ToJson(response);
    }

    /// <summary>
    /// アプリケーションを削除
    /// </summary>
    [HttpDelete]
    public HttpResponseMessage Remove(int id)
    {
        var response = new ApiResponse { StatusCode = 200, Message = "正常に削除されました" };
        return JsonHelper.ToJson(response);
    }
}

XMLコメントの表示設定

Swagger UI上でXMLドキュメント（コメント）を表示するには、SwaggerConfigに設定を追加する必要があります。

public class SwaggerConfig
{
    public static void Register()
    {
        var assembly = typeof(SwaggerConfig).Assembly;

        GlobalConfiguration.Configuration
            .EnableSwagger(c =>
            {
                c.SingleApiVersion("v1", "SampleApi");
                c.IncludeXmlComments(GetXmlPath());
            })
            .EnableSwaggerUi(c =>
            {
            });
    }
    
    private static string GetXmlPath()
    {
        return string.Format("{0}/bin/SampleApi.XML", AppDomain.CurrentDomain.BaseDirectory);
    }
}

c.IncludeXmlComments(GetXmlPath())の行を追加することで、APIの説明やパラメータの注釈がSwagger UIに表示されるようになります。これにより、APIを利用する開発者が各エンドポイントの役割を理解しやすくなります。

まとめ

本稿では、.NET WebAPIプロジェクトにSwaggerを導入する手順と、遭遇する可能性のあるエラーの解决方法について説明しました。Swaggerを導入することで、APIのドキュメント化が容易になり、デバッグやチーム開発が効率化されます。特にXMLコメントを表示させることで、APIの可読性と使いやすさが大幅に向上します。