Freshness Update: web-api-help-pages-sing-swagger

[wadepickett]

Description

Contributes to #36100

AI generated freshness report:

Run by: WadePickett

Review Report: web-api-help-pages-using-swagger.md

File: aspnetcore/tutorials/web-api-help-pages-using-swagger.md
Repository: dotnet/AspNetCore.Docs
Reviewed: 2026-02-23
Reviewer: @wadepickett

---

Overview

This article covers ASP.NET Core web API documentation with Swagger/OpenAPI. After a thorough review against the repository's copilot instructions and the current state of ASP.NET Core OpenAPI support, this article needs updating.

---

Verdict: Needs Updating

---

Critical Issues

It is by design that the article's `monikerRange` is capped at `aspnetcore-8.0 since starting with .NET 9, ASP.NET Core Swashbuckle was replaced as the default OpenAPI approach with the built-in `Microsoft.AspNetCore.OpenApi` package. The repository already has dedicated OpenAPI documentation for .NET 9+ at:

* `aspnetcore/fundamentals/openapi/overview.md` (uid: `fundamentals/openapi/overview`)
* `aspnetcore/fundamentals/openapi/aspnetcore-openapi.md` (uid: `fundamentals/openapi/aspnetcore-openapi`)

**Assessment:** The capped moniker range is intentional and correct for this article's Swashbuckle/NSwag content. However, the 8.0 article should explicitly guide readers developing with .NET 9+ to the newer OpenAPI documentation rather than leaving them with no visible content

###  No guidance directing .NET 9+ users to the new OpenAPI docs

### Stale `ms.date` format and value

**Location:** Frontmatter, line 8

```yaml
ms.date: 4/25/2024

• The format should be MM/DD/YYYY per the repo guidelines (should be 04/25/2024).
• The date itself is nearly two years old and should be updated to today's date if any content changes are made.

4. Bash placeholder casing doesn't follow repo conventions

Location: Line 150

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json

Per the copilot instructions, placeholders should use uppercase with spaces between words: {TOKEN} and {PORT}. The current {token} and {port} don't conform. Additionally, placeholder descriptions should be provided in the surrounding text.

Should be:

curl -i -H "Authorization: Bearer {TOKEN}" https://localhost:{PORT}/swagger/v1/swagger.json

With surrounding text explaining: "where the {TOKEN} placeholder is the JWT bearer token and the {PORT} placeholder is the port number."

---

Moderate Issues

5. Missing "not latest version" banner, however it is not needed in this case.

The fundamentals/openapi/overview.md article includes [!INCLUDE[](~/includes/not-latest-version.md)] for versioned content, but this Swagger article does not. There is good reason for this. Since the article only applies to <= aspnetcore-8.0, adding this include would help readers understand they're viewing older content.

6. Trailing period in section header

Location: Line 155

## Generate an XML documentation file at compile time.

Per the Microsoft Writing Style Guide and repo conventions, section headers should not end with a period.

Should be:

## Generate an XML documentation file at compile time

--

What's Good (No Changes Needed)

• ✅ Cross-references use proper xref: syntax (e.g., xref:tutorials/get-started-with-swashbuckle)
• ✅ External links (GitHub repos, swagger.io) use full URLs
• ✅ The Microsoft Learn link for GenerateDocumentationFile uses the correct relative format without locale
• ✅ The API xref for RequireAuthorization uses proper encoding
• ✅ Code snippet reference syntax (:::code) is correctly formatted
• ✅ Bullet markers use * as required by the repo
• ✅ OpenAPI specification JSON example is helpful and well-formatted
• ✅ Metadata has title first, with remaining fields in alphabetical order

---

Proposed NOTE for .NET 9+ Users

The NOTE

> [!NOTE]
> In .NET 9 and later, ASP.NET Core includes built-in OpenAPI support. Swashbuckle is no longer included by default, but it remains available as a community package you can add manually to ASP.NET Core projects targeting .NET 9 or later.
> 
> • To understand the built‑in OpenAPI features, see <xref:fundamentals/openapi/overview?view=aspnetcore-9.0&preserve-view=true>.  
> • To add and use the Swagger UI provided by the `Swashbuckle.AspNetCore.SwaggerUI` package for interactive exploration or local ad‑hoc testing, see <xref:fundamentals/openapi/using-openapi-documents#use-swagger-ui-for-local-ad-hoc-testing>.
>
>The following instructions apply when using Swashbuckle with .NET versions earlier than 9.

Analysis: Does this NOTE belong in the article?

Yes. This NOTE is highly valuable and should be added. Here's the reasoning:

1. Discoverability: Users who find this article via search engines, bookmarks, or internal xref links from other docs may be working on .NET 9+ projects. Without this note, they see either nothing (if the moniker range excludes them) or outdated guidance (if they manually select ASP.NET Core 8.0). This note bridges that gap.

2. Accuracy: The note correctly states:

   • Swashbuckle was removed from the default templates in .NET 9.
   • Swashbuckle remains available as a community package.
   • Built-in support now exists via Microsoft.AspNetCore.OpenApi.
   • The xref links point to the correct modern documentation.

3. The final sentence ("The following instructions apply when using Swashbuckle with .NET versions earlier than 9.") clearly scopes the rest of the article, preventing reader confusion.

Which .NET version(s) / moniker ranges should include this NOTE?

Placement	Moniker Range	Rationale
Primary placement	>= aspnetcore-8.0 (the existing 8.0 moniker block in the main file)	This is the highest versioned content block readers can currently see. Placing the NOTE at the top of this block (immediately after the "By Rico Suter" byline) ensures that readers viewing the ASP.NET Core 8.0 version — which is the most recent version shown — are informed of the .NET 9+ transition before they proceed with the Swashbuckle-based instructions.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-8.0&viewFallbackFrom=aspnetcore-10.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/tutorials/web-api-help-pages-using-swagger.md

Document ID

2994cf60-0cb7-afa2-20b8-7e2b1117f964

Platform Id

3167ab2d-d7c5-0b0d-ea76-0c645ab442fe

Article author

@RicoSuter

Metadata

• ID: f34eea37-51a4-6227-f5ed-6501624ad045
• PlatformId: 3167ab2d-d7c5-0b0d-ea76-0c645ab442fe
• Service: aspnet-core
• Sub-service: tutorials

Related Issues

---

Associated WorkItem - 554844