Swashbuckle.AspNetCore.Annotations is an optional NuGet module that lets ASP.NET Core developers enrich generated OpenAPI documentation with attributes placed directly on endpoints and parameters. section 11.2.2 section 11.2.4
A practical setup follows these steps:
- Install the Swashbuckle.AspNetCore.Annotations package through Visual Studio, the Package Manager Console, or the .NET CLI. section 11.2.4
- Add [SwaggerOperation] to controller actions or Minimal API methods to define custom summaries, descriptions, and tags. section 11.2.4
- Place [SwaggerParameter] directly above the input parameter it describes. section 11.2.4
- Enable annotation processing globally with options.EnableAnnotations() inside AddSwaggerGen. section 11.2.4
Board-game API documentation
A BoardGamesController can describe its list endpoint with the summary “Get a list of board games” and explain its paging, sorting, and filtering behavior. Its query parameter can receive a [SwaggerParameter] description identifying the DTO used to customize retrieval. 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
Inspect the complete controller example, including annotations on multiple board-game operations. section 11.2.4
builder.Services.AddSwaggerGen(options =>
{
options.EnableAnnotations(); #1
// ... existing code
Inspect the required global AddSwaggerGen configuration. section 11.2.4
