Freshness update: web-api-help-pages-using-swagger.md

[Copilot]

• Add ai-usage: ai-assisted to frontmatter
• Fix ms.date format/value to 02/23/2026
• Add guidance for .NET 9+ users (converted from NOTE to introduction paragraphs per reviewer feedback)
• Fix placeholder casing in curl command: {TOKEN}, {PORT}, with explanatory text
• Remove trailing period from section header

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Freshness Update: web-api-help-pages-sing-swagger</issue_title>
<issue_description>### 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...

• Fixes Freshness Update: web-api-help-pages-sing-swagger #36786

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/tutorials/web-api-help-pages-using-swagger.md	aspnetcore/tutorials/web-api-help-pages-using-swagger

[wadepickett]

Approved after I committed a few fixes to the AI gen original PR.

[wadepickett]

@copilot, move this into an introduction paragraph rather than a note as it is now, it is currently on line 18 of aspnetcore/tutorials/web-api-help-pages-using-swagger.md:

Note

This article covers using Swagger tooling — provided by the Swashbuckle.AspNetCore and NSwag packages — to generate OpenAPI documentation and interactive help pages for ASP.NET Core web APIs.

In .NET 9 and later, ASP.NET Core includes built-in OpenAPI support that replaces Swashbuckle as the default. Swashbuckle is no longer included in project templates, but it remains available as a community package you can add manually.

[Copilot]

@copilot, move this into an introduction paragraph rather than a note as it is now, it is currently on line 18 of aspnetcore/tutorials/web-api-help-pages-using-swagger.md:

[!NOTE]...

Done in commit 80829a9. The [!NOTE] callout has been converted to plain introduction paragraphs.

[wadepickett]

Approved after a number of commits to improve which have now been merged.