Add Description to ProducesResponseType (and others) for better OpenAPI documents

[sander1095]

Background and Motivation

The purpose of this API Change is to make it easier for developers to add the Description properties to their OpenAPI documents using the [ProducesResponseType], [Produces] and [ProducesDefaultResponseType] attributes in controller actions.

Developers currently use these properties to enrich the OpenAPI document of the API. It tells the reader the possible return values from an endpoint, like a status code, response model type and content type:

See code + OpenAPI example

[HttpGet("{id:int:min(1)}")]
[ProducesResponseType<Talk>(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ActionResult<Talk> GetTalk(int id)
{
    var talk = _talks.FirstOrDefault(x => x.Id == id);
    if (talk == null)
    {
        return NotFound();
    }

    return Ok(talk);
}

OpenAPI document is generated using NSwag (I used a JSON to YAML converter)

paths:
  "/api/talks/{id}":
    get:
      tags:
      - Talks
      operationId: Talks_GetTalk
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
        x-position: 1
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Talk"
        '404':
          description: ''
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ProblemDetails"

However, there is currently no way to map OpenAPIs description using attributes, which is the easiest way to enrich your methods with OpenAPI information which also works well with the OpenAPI analyzers.

It's important to make it easy for developers to set up the Description property because this adds a lot of important information to a specific response. For example, if an API returns HTTP 422, it would be useful to add a description explaining why/when this error is returned. Without this, handling this error in the client becomes more difficult because the meaning is lost.

There are other ways to set the Description right now, but I'm not a big fan of them. I explain why in Alternative designs below.

I've wanted this feature in ASP.NET Core for a while. I've created this API proposal after talking to @captainsafia about this at the MVP Summit 2024, and she agreed that this would be a worthy addition. I had already created #54064 for this at some point. I hope the rest of the team/community agrees!

Proposed API

This list might be incomplete. I would welcome help finding the impact this has in other files. For more detailed changes, see my ongoing work.

The Description would be added to IApiResponseMetadataProvider which is implemented by [Produces], [ProducesDefaultResponseType] and [ProducesResponseType]:

namespace Microsoft.AspNetCore.Mvc.ApiExplorer;

/// <summary>
/// Provides a return type, status code and a set of possible content types returned by a
/// successful execution of the action.
/// </summary>
public interface IApiResponseMetadataProvider : IFilterMetadata
{
    /// <summary>
    /// Gets the optimistic return type of the action.
    /// </summary>
    Type? Type { get; }

+   /// <summary>
+   /// Gets the description of the response.
+   /// </summary>
+   string? Description { get; }

    /// <summary>
    /// Gets the HTTP status code of the response.
    /// </summary>
    int StatusCode { get; }

    /// <summary>
    /// Configures a collection of allowed content types which can be produced by the action.
    /// </summary>
    void SetContentTypes(MediaTypeCollection contentTypes);
}

I've chosen to only highlight the diff of ProducesResponseType here to keep this proposal brief.
Let me know if you want me to highlight other impacted files like the other attributes.

namespace Microsoft.AspNetCore.Mvc;

/// <summary>
/// A filter that specifies the type of the value and status code returned by the action.
/// </summary>
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
public class ProducesResponseTypeAttribute : Attribute, IApiResponseMetadataProvider
{
     // Existing code here

+   /// <summary>
+   /// Gets the description of the response.
+   /// </summary>
+   public string? Description { get; set; }

     // Existing code here
}

It might also impact other files, like ApiResponseType:

namespace Microsoft.AspNetCore.Mvc.ApiExplorer;

/// <summary>
/// Possible type of the response body which is formatted by <see cref="ApiResponseFormats"/>.
/// </summary>
public class ApiResponseType
{
    // Existing code here

+   /// <summary>
+   /// Gets the description of the response.
+   /// </summary>
+   public string? Description { get; set; }

     // Existing code here
}

Usage Examples

-/// <response code="200">A talk entity when the request is succesful</response>
-/// <response code="422">The entity is unprocessable because SOME_REASON_HERE</response>
[HttpGet("{id:int:min(1)}")]
-[Produces<Talk>]
+[Produces<Talk>(Description = "A talk entity when the request is succesful")]
-[ProducesResponseType<Talk>(StatusCodes.Status200OK)]
+[ProducesResponseType<Talk>(StatusCodes.Status200OK, Description = "A talk entity when the request is succesful")]
-[ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
+[ProducesResponseType(StatusCodes.Status422UnprocessableEntity, Description = "The entity is unprocessable SOME_REASON_HERE")]
// I do not think there is currently a way to specify a description for the default error response type, so this is a nice bonus!
-[ProducesDefaultResponseType]
+[ProducesDefaultResponseType(Description = "The response for all other errors that might be thrown")]
public ActionResult<Talk> GetTalk(int id)
{
    var talk = _talks.FirstOrDefault(x => x.Id == id);
    if (talk == null)
    {
        return NotFound();
    }

    if (someCondition)
    {
        return UnprocessableEntity();
    }

    return Ok(talk);
}

Alternative Designs

XML comments

An alternative design is to do nothing and use the built-in solution, which are XML comments:

/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

This will fill the description properties with the values from the <response> tags.

However:

• This becomes quite verbose when you're combining [ProducesResponseType] (and the other ones mentioned above) and XML comments.
• We're duplicating XML comments and produces response type attributes, which isn't ideal because now we need to manage the same code twice, which will get out of sync over time.
• I do not believe that the <response> can set a description for [ProducesDefaultResponseType]

To summarize: I do not think that XML comments is the correct one.

Library specific attributes

Both Swashbuckle.AspNetCore and NSwag have their own versions of [ProducesResponseType] called [SwaggerResponse] that do support the OpenAPI Description property.

However, there are several downsides to this:

• They are library specific, wheras [ProducesResponseType] is library agnostic. By using [ProducesResponseType] I could switch from Swashbuckle to NSwag and the OpenAPI document generation should keep working, which isn't guaranteed if I used a library specific attribute.
• Trying to combine NSwag's [SwaggerResponse] with [ProducesResponseType] to set up response descriptions doesn't work. When [SwaggerResponse] is used, all instances of [ProducesResponseType] are ignored for that method.
  • This means that some methods need to use [SwaggerResponse] for description support and others can still use [ProducesResponseType], which makes things more difficult to read because their method signature is different.
• The OpenAPI analyzer doesn't work with library-specific attributes like [SwaggerResponse], which means I need to disable those warnings for specific methods, which is annoying and makes code more difficult to read.

If ASP.NET Core's [ProducesResponseType] would support things like Description, the library-specific versions attributes might not be needed anymore, which makes it even easier to switch libraries in the future.

Risks

Swashbuckle.AspNetCore's SwaggerResponse [ProducesResponseType] and already has its own Description property, which means that this change might cause some issues for them. However, .NET 9 won't ship Swashbuckle anymore by default, reducing the impact this has. Regardless, Swashbuckle's authors should be informed of this change.

[sander1095]

Note: In case this proposal gets accepted, I would love to be the "main author" for getting this implemented in ASP.NET Core (Though help would definitely be welcome!).

[martincostello]

Swashbuckle.AspNetCore's SwaggerResponse [ProducesResponseType] and already has its own Description property, which means that this change might cause some issues for them. However, .NET 9 won't ship Swashbuckle anymore by default, reducing the impact this has. Regardless, Swashbuckle's authors should be informed of this change.

Consider us informed 😄

We'll happily accept a PR (once we have a branch for .NET 9 support open) to add support for this if it's approved.

[captainsafia]

@sander1095 Thanks for getting this issue together!

The one gap I notice is that this proposal primarily targets the ProducesResponseType attributes associated with MVC and not the Produces metadata/attributes/extension methods for minimal API.

[sander1095]

I am unfamiliar with using attributes in minimal API's, I thought it was all extension method based on the MapGet/MapPost/MapEtc.. methods.

Description is already a first class citizen in minimal API.

However, I have nothing against adding more OpenAPI description support in both Controllers and Minimal API's.😁

EDIT: I just realized that I got the the Description of an endpoint confused with the Description of a response. Woops! In case this is not supported yet in the minimal api model, I 100% believe it should be added!