Swashbuckle参数说明
Sli*_*icc 19 c# swagger swashbuckle
我正在使用SwaggerResponse属性来装饰我的api控制器动作,这一切都运行正常,但是当我查看生成的文档时,参数的描述字段为空.
是否有基于属性的方法来描述操作参数(而不是XML注释)？
Jul*_*iën 27
使用最新的Swashbuckle,或者更好地说至少我正在使用的Swashbuckle.AspNetCore变体,参数的Description字段现在可以正确显示为输出.
它确实需要满足以下条件:
- 必须使用Swagger启用和配置XML注释
- 应使用[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);
}
其中产生以下输出:
- 有没有办法继承这些评论？例如，当我有一个 crudcontroller 时。和我所有的控制器（客户，客户，订单，）等等。从这个控制器继承。我可以为基本控制器中的参数指定注释/描述并让我的客户控制器继承吗？ (3认同)
- 除了答案中提到的要求之外，描述显示的必要先决条件是首先通过 csproj 中的 `<PropertyGroup><DocumentationFile>` 为您的项目生成 xml 注释，然后将它们注册到您的 `services 中.AddSwaggerGen()` 通过 `IncludeXmlComments(filePath);`。 (2认同)
您应该确认您允许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文档文件