为ASP.NET核心中的未绑定参数添加swagger参数

在ASP.NET Core中，Swagger（现在称为OpenAPI）用于生成API文档，使开发者能够轻松理解和测试API。当你在API控制器中使用未绑定的参数时，例如通过[HttpGet]属性定义的查询字符串参数，你需要确保这些参数在Swagger文档中正确显示。

基础概念

Swagger/OpenAPI：一种用于描述、生成、消费和可视化RESTful网络服务的机器可读接口文件的规范。
ASP.NET Core：一个开源且跨平台的框架，用于构建Web应用程序和API。

类型

查询参数：通过URL传递的参数，如/api/items?name=value。
路径参数：嵌入在URL路径中的参数，如/api/items/{id}。
请求体参数：通过HTTP请求体发送的参数，通常用于POST、PUT等请求。

应用场景

当你有一个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;
        }
    }
}