Action添加额外ProducesResponseType时ASP.NET Core Web API约定失效求解决

问题背景 #

首先定义了全局API约定类，用于统一标记Get类接口的404响应：

public static class MyAppConventions
{
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound,
                          MediaTypeNames.Application.ProblemJson)]
    [ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
    public static void Get()
    { }
}

控制器应用该约定后，默认会继承约定中的404响应配置：

[ApiConventionType(typeof(MyAppConvention))]
[Route("test")]
public class TestController : ControllerBase
{
    [HttpGet]
    public IActionResult GetData()
    {
        if (condition)
            return NotFound();
        else
            return Ok(new TestDto());
    }
}

问题描述 #

当在Action上额外添加ProducesResponseType以标记约定中未覆盖的200响应类型时，约定中的404响应会被系统忽略，导致OpenAPI分析器无法识别该状态码。修改后的控制器代码如下：

[ApiConventionType(typeof(MyAppConvention))]
[Route("test")]
public class TestController : ControllerBase
{
    [ProducesResponseType(typeof(TestDto), StatusCodes.Status200Ok, MediaTypeNames.Application.Json)]
    [HttpGet]
    public IActionResult GetData()
    {
        if (condition)
            return NotFound();
        else
            return Ok(new TestDto());
    }
}

可行解决办法 #

1. 给约定补充通用成功响应占位 #

在约定的Get方法中添加一个通用的200响应（用void作为占位类型），这样Action上的具体200响应会覆盖这个占位，而约定中的404响应会被保留：

public static class MyAppConventions
{
    // 添加通用200占位，让Action的具体响应覆盖它
    [ProducesResponseType(typeof(void), StatusCodes.Status200Ok)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound, MediaTypeNames.Application.ProblemJson)]
    [ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
    public static void Get()
    { }
}

这样OpenAPI分析器会同时识别到Action的200响应和约定的404响应。

2. 手动在Action上重复约定的响应属性 #

如果上述方法无效，可以直接在Action上显式添加约定中的404响应属性，确保所有需要的状态码都被OpenAPI分析器识别：

[ApiConventionType(typeof(MyAppConvention))]
[Route("test")]
public class TestController : ControllerBase
{
    [ProducesResponseType(typeof(TestDto), StatusCodes.Status200Ok, MediaTypeNames.Application.Json)]
    // 手动添加约定中的404响应属性
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound, MediaTypeNames.Application.ProblemJson)]
    [HttpGet]
    public IActionResult GetData()
    {
        if (condition)
            return NotFound();
        else
            return Ok(new TestDto());
    }
}

这种方式虽然会增加代码重复，但能快速解决问题。

3. 使用泛型约定类匹配特定返回类型 #

创建泛型约定类，让控制器可以指定对应的返回Dto类型，避免在Action上单独添加ProducesResponseType：

public static class MyAppConventions<T>
{
    [ProducesResponseType(typeof(T), StatusCodes.Status200Ok, MediaTypeNames.Application.Json)]
    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound, MediaTypeNames.Application.ProblemJson)]
    [ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
    public static void Get()
    { }
}

然后在控制器上应用泛型约定：

// 指定泛型参数为当前Action的返回Dto类型
[ApiConventionType(typeof(MyAppConventions<TestDto>))]
[Route("test")]
public class TestController : ControllerBase
{
    [HttpGet]
    public IActionResult GetData()
    {
        if (condition)
            return NotFound();
        else
            return Ok(new TestDto());
    }
}

这种方法既保留了约定的复用性，又能准确识别每个Action的返回类型。

内容的提问来源于stack exchange，提问作者AkshatSparrow