Excluding endpoints from OpenAPI document when using controllers

[davidkarlsson]

I've been trying out the controller support for generating OpenAPI documentation in .NET 9 preview 7 using Microsoft.AspNetCore.OpenApi and noticed that I can't use the ExcludeFromDescriptionAttribute for excluding controller actions from the generated OpenAPI document. The documentation also clearly states that this attribute is just for excluding endpoints when using minimal APIs so it's perhaps not that surprising that it doesn't work for controllers/actions.

After some digging I found that I can instead use the ApiExplorerSettingsAttribute for excluding controller actions from the OpenAPI document by setting its IgnoreApi property to true. I guess my question is if that's is going to be the only way to exclude endpoints when using controllers? Or should it also be possible to use ExcludeFromDescriptionAttribute for controllers as well but support for it just hasn't been added yet? And if ApiExplorerSettingsAttribute is going to be the only way to exclude controller actions shouldn't that also be documented at the same place as the documentation for ExcludeFromDescriptionAttribute in the "Work with OpenAPI documents" doc?

[martincostello]

I've been using ExcludeFromDescription() to exclude endpoints from my OpenAPI documents, which just adds an ExcludeFromDescriptionAttribute to the endpoint metadata, and that's been working as expected with Microsoft.AspNetCore.OpenApi.

Sounds like maybe you're just hitting a bug - could you open a new issue with a Minimal Reproducible Example of the issue, then one of the engineers will be able to take a look into it.

[davidkarlsson]

Ok but are you using ExcludeFromDescriptionAttribute with controllers/actions or with minimal API? My question was specifically about being able to use it with controller actions which doesn't seem to work and I instead have to use the ApiExplorerSettingsAttribute for it which isn't documented in the OpenAPI docs.

Here's a small repro of what I'm referring to:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

builder.Services.AddControllersWithViews();

var app = builder.Build();

app.UseRouting();

app.UseAuthorization();

app.MapOpenApi();

app.Run();


[ApiController]
[Route("Api/[action]")]
public class PublicApiController : ControllerBase
{
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public IActionResult Public()
    {
        return Ok();
    }
}


[ApiController]
[Route("Api/[action]")]
[ExcludeFromDescription]
//[ApiExplorerSettings(IgnoreApi = true)]
public class InternalApiController : ControllerBase
{
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public IActionResult Internal()
    {
        return Ok();
    }
}

The Internal endpoint is still included in the OpenAPI document and only using ApiExplorerSettings(IgnoreApi = true) removes it:

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenApiTest | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://localhost:5001"
    }
  ],
  "paths": {
    "/Api/Internal": {
      "get": {
        "tags": [
          "InternalApi"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/Api/Public": {
      "get": {
        "tags": [
          "PublicApi"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": { },
  "tags": [
    {
      "name": "InternalApi"
    },
    {
      "name": "PublicApi"
    }
  ]
}

[martincostello]

Yep, I get that it's Controllers not Minimal APIs (which is what I'm using), but I would have thought that the OpenApi functionality would just be consuming the endpoint metadata in the same way and as they both use the same type, then they both should work.

Either way, I think this is a bug given that the Minimal APIs is using the same attribute to signify that it shouldn't be documented.

[davidkarlsson]

Thanks @martincostello! I created an issue about this here #57425 now.