Introduction

ProducesResponseType in ASP.NET Core is primarily metadata. It tells API exploration and documentation tools which HTTP status codes and response types an endpoint is expected to produce, but it does not by itself create those responses at runtime.

What the Attribute Actually Does

The attribute is used on controllers or actions to describe possible outcomes. Tools built on ASP.NET Core’s API explorer, such as Swagger or OpenAPI generators, read that metadata and include it in the generated contract.

Basic example:

1using Microsoft.AspNetCore.Http;
2using Microsoft.AspNetCore.Mvc;
3
4[ApiController]
5[Route("users")]
6public class UsersController : ControllerBase
7{
8    [HttpGet("{id:int}")]
9    [ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)]
10    [ProducesResponseType(StatusCodes.Status404NotFound)]
11    public ActionResult<UserDto> GetById(int id)
12    {
13        if (id != 1)
14        {
15            return NotFound();
16        }
17
18        return Ok(new UserDto(id, "Ada"));
19    }
20}
21
22public record UserDto(int Id, string Name);

This tells tooling that the endpoint may return a 200 with a UserDto body or a 404 with no body specified.

What It Does Not Do

A very common misunderstanding is assuming the attribute enforces runtime behavior. It does not.

This code still controls the real response:

return Ok(new UserDto(id, "Ada"));
return NotFound();

If the implementation returns a different status code than the attribute documents, the framework will not magically correct it. The attribute describes intent; the action result still determines behavior.

Why It Is Useful Anyway

Even though it is only metadata, that metadata matters.

It improves:

• OpenAPI documentation
• client generation
• endpoint readability for other developers
• API review quality

A well-documented action makes it obvious which success and error cases the endpoint is designed to support.

For example, an endpoint that can return validation errors, missing-resource errors, and success should not force consumers to guess that from the implementation alone.

Multiple Response Types Are Normal

Real endpoints often have several documented outcomes.

1[HttpPost]
2[ProducesResponseType(typeof(UserDto), StatusCodes.Status201Created)]
3[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
4[ProducesResponseType(StatusCodes.Status409Conflict)]
5public ActionResult<UserDto> Create(CreateUserRequest request)
6{
7    if (string.IsNullOrWhiteSpace(request.Name))
8    {
9        return ValidationProblem();
10    }
11
12    if (request.Name == "existing")
13    {
14        return Conflict();
15    }
16
17    var user = new UserDto(2, request.Name);
18    return CreatedAtAction(nameof(GetById), new { id = user.Id }, user);
19}
20
21public record CreateUserRequest(string Name);

That gives documentation consumers a much more accurate picture than only documenting the happy path.

Relationship to [ApiController]

When [ApiController] is enabled, ASP.NET Core automatically returns 400 Bad Request for invalid model state in many common cases. Developers sometimes assume that response will automatically appear in documentation too.

Sometimes tooling can infer some responses, but relying on inference makes the contract less explicit. If the endpoint is meant to return a validation payload, documenting it with ProducesResponseType keeps the API description clearer.

ProducesResponseType Versus Produces

ProducesResponseType says which status code and CLR type belong to a possible response.

Produces is different. It describes the response content type, such as application/json.

Example:

[Produces("application/json")]
[ProducesResponseType(typeof(UserDto), StatusCodes.Status200OK)]

These attributes solve related but different problems:

• 'Produces describes media type'
• 'ProducesResponseType describes status code and body type'

A Good Practical Rule

Document the responses that matter to clients, not every theoretical framework outcome. For example:

• success responses
• validation failures
• not found for lookup endpoints
• conflict for uniqueness or concurrency problems
• unauthorized or forbidden if security is part of the contract

That keeps the API documentation useful instead of noisy.

Common Pitfalls

The biggest mistake is assuming ProducesResponseType changes runtime behavior. It does not create, validate, or enforce the actual response.

Another mistake is documenting only 200 OK and ignoring the error responses clients must handle. That makes generated documentation incomplete and misleading.

Developers also sometimes put the wrong CLR type on the attribute, which causes the documentation to advertise a response schema the endpoint does not really return.

Finally, do not confuse ProducesResponseType with content negotiation metadata. Status codes, body types, and media types are related, but they are not the same thing.

Summary

• 'ProducesResponseType is API metadata, mainly for documentation and API exploration.'
• It does not force the action to return the documented status code or body.
• Use it to describe real success and error responses that clients should expect.
• It works well with Swagger or OpenAPI generation because tools can read it directly.
• Keep the documented response types aligned with what the action actually returns.