在ASP.NET Core中,Swagger(现在称为OpenAPI)用于生成API文档,使开发者能够轻松理解和测试API。当你在API控制器中使用未绑定的参数时,例如通过[HttpGet]
属性定义的查询字符串参数,你需要确保这些参数在Swagger文档中正确显示。
/api/items?name=value
。/api/items/{id}
。当你有一个API端点,它依赖于查询字符串参数来执行操作时,例如搜索功能:
[HttpGet("search")]
public IActionResult Search(string query)
{
// 实现搜索逻辑
}
如果你发现Swagger文档中没有显示这个query
参数,你需要使用Swagger的注解来显式地告诉Swagger这个参数的存在。
在你的控制器方法上添加[ApiExplorerSettings(IgnoreApi = false)]
属性,以确保Swagger不会忽略这个方法。然后,在方法参数上添加[FromQuery]
和[SwaggerParameter]
属性来指定这是一个查询参数,并提供额外的描述信息。
using Microsoft.AspNetCore.Mvc;
using Swashbuckle.AspNetCore.Annotations;
[ApiController]
[Route("api/[controller]")]
public class ItemsController : ControllerBase
{
[HttpGet("search")]
[ApiExplorerSettings(IgnoreApi = false)]
public IActionResult Search([FromQuery] string query, [SwaggerParameter("搜索关键词", Required = true)] string query)
{
// 实现搜索逻辑
return Ok($"Search results for: {query}");
}
}
注意:上面的代码中[SwaggerParameter]
属性实际上并不存在于Swashbuckle.AspNetCore.Annotations
命名空间中。正确的做法是使用[SwaggerRequestParameter]
属性(如果你使用的是较旧版本的Swashbuckle)或者使用[OpenApiParameter]
属性(如果你使用的是最新版本的Swashbuckle)。以下是使用[OpenApiParameter]
的示例:
using Microsoft.AspNetCore.Mvc;
using Swashbuckle.AspNetCore.Annotations;
[ApiController]
[Route("api/[controller]")]
public class ItemsController : ControllerBase
{
[HttpGet("search")]
public IActionResult Search([FromQuery] string query)
{
// 实现搜索逻辑
return Ok($"Search results for: {query}");
}
}
// 在Startup.cs或Program.cs中配置Swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "API", Version = "v1" });
// 添加参数描述
c.ParameterFilter<OpenApiParameterFilter>();
});
public class OpenApiParameterFilter : IParameterFilter
{
public void Apply(OpenApiParameter parameter, ParameterFilterContext context)
{
if (parameter.Name == "query")
{
parameter.Description = "搜索关键词";
parameter.Required = true;
}
}
}
确保你的项目中安装了最新版本的Swashbuckle.AspNetCore包,并且在Startup.cs
或Program.cs
中正确配置了Swagger。
领取专属 10元无门槛券
手把手带您无忧上云