web-dev-qa-db-ja.com

スワッシュバックルのパラメーターの説明

SwaggerResponse属性を使用してAPIコントローラーアクションを装飾しますが、これはすべて正常に機能しますが、生成されたドキュメントを見ると、パラメーターの説明フィールドが空です。

XMLコメントではなく、アクションパラメータを記述する属性ベースのアプローチはありますか？

c#swaggerswashbuckle
18
Slicc

最新のスワッシュバックル、または少なくとも私が使用している Swashbuckle.AspNetCoreバリアント 、パラメーターのDescriptionフィールドが出力として正しく表示されるようになりました。

次の条件を満たしている必要があります。

  • XMLコメント Swaggerを有効にして構成する必要があります
  • パラメーターは、[FromRoute]、[FromQuery]、[FromBody]、または[FromUri]で明示的に装飾する必要があります
  • メソッドタイプ（get/post/putなど）でも同じです。[Http...]で修飾する必要があります
  • <param ...> xmlコメントを使用して、通常どおりパラメーターを記述します

完全なサンプルは次のようになります。

/// <summary>
/// Short, descriptive title of the operation
/// </summary>
/// <remarks>
/// More elaborate description
/// </remarks>
/// <param name="id">Here is the description for ID.</param>
[ProducesResponseType(typeof(Bar), (int)HttpStatusCode.OK)]
[HttpGet, Route("{id}", Name = "GetFoo")]
public async Task<IActionResult> Foo([FromRoute] long id)
{
    var response = new Bar();
    return Ok(response);
}

次の出力が生成されます。

Swagger output with parameter description

27
Juliën

SwaggerにXMLコメントの使用を許可していることを確認する必要があります

httpConfig.EnableSwagger(c => {
                if (GetXmlCommentsPath() != null) {
                    c.IncludeXmlComments(GetXmlCommentsPath());
                }
...
...
);

protected static string GetXmlCommentsPath() {
    var path = HostingEnvironment.MapPath("path to your xml doc file");
    return path;
}

また、目的のプロジェクトのXMLドキュメントを生成していることも確認する必要があります。目的のプロジェクトの下でプロパティ（プロジェクトの上でAlt + Enterまたは右クリック->プロパティ）-> ビルド->チェックXMLドキュメントファイル =

5
Alfredo A.

完全を期すために、Swashbuckle.AspNetCore (2.1.0)およびSwashbuckle.SwaggerGen/Ui (6.0.0)の最新バージョンを使用する場合は、プロジェクトのビルドでXmlドキュメントファイルの生成を有効にしてください

その後、次のConfigureServices()メソッドに：

services.ConfigureSwaggerGen(options =>
{
    options.SingleApiVersion(new Info
    {
        Version = "v1",
        Title = "My API",
        Description = "API Description"
    });
    options.DescribeAllEnumsAsStrings();

    var xmlDocFile = Path.Combine(AppContext.BaseDirectory, $"{_hostingEnv.ApplicationName}.xml");
    if (File.Exists(xmlDocFile))
    {
        var comments = new XPathDocument(xmlDocFile);
        options.OperationFilter<XmlCommentsOperationFilter>(comments);
        options.ModelFilter<XmlCommentsModelFilter>(comments);
    }
});
0
Adriaan de Beer