web-dev-qa-db-ja.com

Web APIアプリケーションのSwagger UIでメソッドの説明を追加する方法

APIツールのフレームワークとしてSwaggerを使用していますが、これまでのところうまく機能しています。このページに出会ったばかりです https://petstore.swagger.io/

各メソッドにどのように説明があるかを見ました。例えば、

_POST: pet/_は_add a new Pet to the store_で記述されます。 [Description("Description text")]のようなものを追加する必要があると思いましたが、それはしません。どうすればこれを達成できますか？

c#asp.net-core-webapiswagger-uirestful-urlswashbuckle
10
Lost

これはプロジェクトでよく文書化されています： https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments

XMLコメントの説明を含める

生成されたドキュメントをわかりやすい説明で強化するには、コントローラーアクションとモデルに Xml Comments で注釈を付け、出力されたSwagger JSONにこれらのコメントを組み込むようにSwashbuckleを構成します。

1-プロジェクトの[プロパティ]ダイアログを開き、[ビルド]タブをクリックして、[XMLドキュメントファイル]がオンになっていることを確認します。これにより、ビルド時にすべてのXMLコメントを含むファイルが作成されます。

この時点で、XMLコメントが注釈されていないクラスまたはメソッドは、ビルド警告をトリガーします。これを抑制するには、プロパティダイアログの[警告の抑制]フィールドに警告コード「1591」を入力します。

2-生成されたSwagger JSONにファイルのXMLコメントを組み込むようにSwashbuckleを構成します。

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
        new Info
        {
            Title = "My API - V1",
            Version = "v1"
        }
     );

     var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
     c.IncludeXmlComments(filePath);
}

3-要約、注釈、応答タグを使用してアクションに注釈を付けます。

/// <summary>
/// Retrieves a specific product by unique id
/// </summary>
/// <remarks>Awesomeness!</remarks>
/// <response code="200">Product created</response>
/// <response code="400">Product has missing/invalid values</response>
/// <response code="500">Oops! Can't create your product right now</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(Product), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(500)]
public Product GetById(int id)

4-サマリータグとサンプルタグでタイプに注釈を付けることもできます。

public class Product
{
    /// <summary>
    /// The name of the product
    /// </summary>
    /// <example>Men's basketball shoes</example>
    public string Name { get; set; }

    /// <summary>
    /// Quantity left in stock
    /// </summary>
    /// <example>10</example>
    public int AvailableStock { get; set; }
}

5-プロジェクトをリビルドしてXMLコメントファイルを更新し、Swagger JSONエンドポイントに移動します。説明が対応するSwaggerフィールドにどのようにマッピングされるかに注意してください。

注：APIモデルとそのプロパティにサマリータグを付けて、Swagger Schemaの説明を提供することもできます。複数のXMLコメントファイルがある場合（コントローラーとモデル用の個別のライブラリなど）、IncludeXmlCommentsメソッドを複数回呼び出すことができ、それらはすべて出力Swagger JSONにマージされます

慎重に指示に従うと、次のようなものが表示されます。
https://swashbucklenetcore.azurewebsites.net/swagger/

26
Helder Sepulveda

追加の属性を使用して、必要な詳細をswaggerドキュメントに追加します。

    [SwaggerOperationSummary("Add a new Pet to the store")]
    [SwaggerImplementationNotes("Adds a new pet using the properties supplied, returns a GUID reference for the pet created.")]
    [Route("pets")]
    [HttpPost]
    public async Task<IHttpActionResult> Post()
    {
        ...
    }

そして、設定を変更する際には、これらのフィルターを必ず適用してください。

config.EnableSwagger("swagger",
           c =>
           {
               c.OperationFilter<ApplySwaggerImplementationNotesFilterAttributes>();
               c.OperationFilter<ApplySwaggerOperationSummaryFilterAttributes>();

フィルターのコード：

public class ApplySwaggerImplementationNotesFilterAttributes : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        var attr = apiDescription.GetControllerAndActionAttributes<SwaggerImplementationNotesAttribute>().FirstOrDefault();
        if (attr != null)
        {
            operation.description = attr.ImplementationNotes;
        }
    }
}

public class ApplySwaggerOperationSummaryFilterAttributes : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        var attr = apiDescription.GetControllerAndActionAttributes<SwaggerOperationSummaryAttribute>().FirstOrDefault();
        if (attr != null)
        {
            operation.summary = attr.OperationSummary;
        }
    }
}
1
Jon Edwards

次のように、ドキュメントにコメントを使用できます（標準2ではなく3つのスラッシュ）。

/// <summary>
/// This is method summary I want displayed
/// </summary>
/// <param name="guid">guid as parameter</param>
/// <param name="page_number">Page number - defaults to 0</param>
/// <returns>List of objects returned</returns>
0
Caldazar