SwaggerResponse属性を使用してAPIコントローラーアクションを装飾しますが、これはすべて正常に機能しますが、生成されたドキュメントを見ると、パラメーターの説明フィールドが空です。
XMLコメントではなく、アクションパラメータを記述する属性ベースのアプローチはありますか?
最新のスワッシュバックル、または少なくとも私が使用している Swashbuckle.AspNetCoreバリアント 、パラメーターのDescriptionフィールドが出力として正しく表示されるようになりました。
次の条件を満たしている必要があります。
[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に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ドキュメントファイル =
完全を期すために、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);
}
});