外部ライブラリを使用した Swagger ドキュメント

将来の場合に備えて、複数のライブラリを使用してコードを分割することは良いことです。個人的には、ロジックを分割して他のプロジェクトやプロジェクトの一部で再利用できるのであれば、そうするのが大好きです。

少なくとも私にとっては、Console application、Blazor application、または API で参照および使用できるように、Entity Framework を含むデータ モデルを分割することが必須です。

私がどのように作業を行っているかの例を見てみましょう。これは、いくつかのアプリケーションとすべてのモデルを含む共有ライブラリを含むプロジェクトのスクリーンショットです。

これは、各プロパティとクラスに関する summary のドキュメントを含む API プロジェクトから移動したクラスの例です。

namespace CustomLibrariesDocumentation.Models
{
    /// <summary>
    /// WeatherForecast class
    /// </summary>
    public class WeatherForecast
    {
        /// <summary>
        /// Gets or sets the Date
        /// </summary>
        public DateOnly Date { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureC
        /// </summary>
        public int TemperatureC { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureF
        /// </summary>
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

        /// <summary>
        /// Gets or sets the Summary
        /// </summary>
        public string? Summary { get; set; }
    }
}

これを Console application に参照し、モデルの使用を開始すると、ドキュメントが表示されます。これは Visual Studio の標準機能であるため、次のように正常に動作します。

しかし、API を参照して Swagger に移動すると、概要ドキュメントは存在しません。

これをどうやって修正すればよいのでしょうか？

まず、ライブラリで XML コメントを有効にする必要があります。これを行うには、プロジェクト設定を更新し、「:」を有効にする必要があります。

これにより、ここに示すように、ファイル拡張子 xml で終わるいくつかのファイルがビルド フォルダーに生成されます。

これが完了したので、これらのファイルを読み込むために Program.cs にいくつかの要素を追加する必要があります。これは、デフォルトでは、そのファイルが存在するプロジェクトの XML 定義のみをロードするためです。

AddSwaggerGen 内にある IncludeXmlComments と呼ばれるメソッドを使用します。

すべての xml ファイルがある場合、それらを Swagger に強制的にロードするという考えです。

builder.Services.AddSwaggerGen(s =>
{
    // Comments
    var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

    foreach (string xmlFiles in allXmlFiles)
    {
        s.IncludeXmlComments(xmlFiles);
    }
});

簡単に言えば、ビルド ディレクトリから xml ファイルを取得し、 IncludeXmlComments メソッドを使用して追加します。

ここで、API を再度ロードし、ドキュメントが表示されるかどうかを確認します。

そして、ドキュメントを見ることができることがわかります。

お役に立てば幸いです。ご質問がございましたら、お気軽にお問い合わせください。