The [SwaggerOperation] attribute adds public-facing metadata to a web API endpoint. Its Summary gives a short label, Description explains what the operation does, and Tags can determine where it appears in SwaggerUI. It works on controller actions and Minimal API methods. section 11.2.4 section 11.2.7
To use it in an ASP.NET Core API:
- Install Swashbuckle.AspNetCore.Annotations, then import its namespace where you annotate endpoints. section 11.2.4
- Place [SwaggerOperation] on an action method or Minimal API handler. Supply a concise Summary and a useful Description. section 11.2.4
- Call options.EnableAnnotations() inside the existing AddSwaggerGen configuration so Swashbuckle processes the attributes. section 11.2.4
Listing 11.1 /Controllers/BoardGamesControllers.cs file: Adding annotations
using Swashbuckle.AspNetCore.Annotations; #1
// ... existing code
[HttpGet(Name = "GetBoardGames")]
[ResponseCache(CacheProfileName = "Any-60")]
[SwaggerOperation( #2
Summary = "Get a list of board games.", #3
Description = "Retrieves a list of board games " + #4
"with custom paging, sorting, and filtering rules.")]
public async Task<RestDTO<BoardGame[]>> Get(
// ... existing code
[HttpGet("{id}")]
[ResponseCache(CacheProfileName = "Any-60")]
[SwaggerOperation(#2
Summary = "Get a single board game.", #3
Description = "Retrieves a single board game with the given Id.")]#4
public async Task<RestDTO<BoardGame?>> Get(int id)
// ... existing code
[Authorize(Roles = RoleNames.Moderator)]
[HttpPost(Name = "UpdateBoardGame")]
[ResponseCache(CacheProfileName = "NoCache")]
[SwaggerOperation(#2
Summary = "Updates a board game.", #3
Description = "Updates the board game's data.")]#4
public async Task<RestDTO<BoardGame?>> Post(BoardGameDTO model)
// ... existing code
[Authorize(Roles = RoleNames.Administrator)]
[HttpDelete(Name = "DeleteBoardGame")]
[ResponseCache(CacheProfileName = "NoCache")]
[SwaggerOperation(#2
Summary = "Deletes a board game.", #3
Description = "Deletes a board game from the database.")]#4
public async Task<RestDTO<BoardGame?>> Delete(int id)
// ... existing code
The board-game GET actions use separate summaries and descriptions: one retrieves a list with paging, sorting, and filtering; the other retrieves a game by ID. section 11.2.4
Use [SwaggerParameter] when an input parameter needs its own description; place it on the parameter rather than on the method. XML documentation comments are another way to describe operations, but [SwaggerOperation] helps keep public API descriptions separate from internal code comments. section 11.2.4 section 11.2.3
Tags also help organize a growing API. Swashbuckle groups controller actions by controller name automatically, while Minimal API endpoints otherwise appear in a generic group. Set Tags on [SwaggerOperation] to give related endpoints a more useful group. Check SwaggerUI or the generated swagger.json to verify the descriptions and grouping. section 11.2.7 section 11.2.4
app.MapGet("/auth/test/1",
[Authorize]
[EnableCors("AnyOrigin")]
[SwaggerOperation(
Tags = new[] { "Auth" }, #1
Summary = "Auth test #1 (authenticated users).",
Description = "Returns 200 - OK if called by " +
"an authenticated user regardless of its role(s).")]
This Minimal API endpoint sets Tags to Auth while retaining its summary and description, creating a group for authentication-related endpoints. section 11.2.7
