Add aspnet-openapi skill (#dotnet-aspnet)

[raihanmehran]

Summary

Adds a new aspnet-openapi skill to the dotnet-aspnet plugin covering OpenAPI documentation for ASP.NET Core APIs. This is a high-frequency, high-confusion area, .NET 9 replaced Swashbuckle as the default in project templates, leaving developers with contradictory guidance across tutorials, and the technology-selection and migration decisions are non-obvious without prior experience.

What's included

• SKILL.md — Full workflow covering:
  • Technology selection: Microsoft.AspNetCore.OpenApi (.NET 9+) vs Swashbuckle vs NSwag, with a clear decision table
  • Setup for both the built-in package and Swashbuckle, including the most common Swashbuckle bug (AddEndpointsApiExplorer() omission)
  • Scalar and Swagger UI setup, with the spec path change called out explicitly
  • Minimal API endpoint annotation (Produces<T>, ProducesProblem, ExcludeFromDescription)
  • JWT Bearer security scheme via IOpenApiDocumentTransformer
  • Securing the spec endpoint in production
• references/transformers.md — Document, operation, and schema transformer patterns; OAuth2 and API key schemes; Swashbuckle IDocumentFilter/IOperationFilter equivalents
• references/swashbuckle-migration.md — Step-by-step migration guide from Swashbuckle including filter→transformer mapping, behavioral differences table, and common post-migration failures
• tests/dotnet-aspnet/aspnet-openapi/eval.yaml — 4 eval scenarios covering basic setup, the Swashbuckle empty-spec gotcha, JWT security scheme configuration, and full Swashbuckle migration

Motivation

dotnet-aspnet currently has a single skill (minimal-api-file-upload). OpenAPI is arguably the most universally needed capability for any HTTP API, every team configures it, and the .NET 9 ecosystem shift means existing documentation and tutorials are inconsistent. This is a clear LLM gap: agents routinely suggest the wrong package for the target framework, omit AddEndpointsApiExplorer(), or produce security scheme configuration that doesn't match the built-in package's transformer API.

[raihanmehran]

@dotnet-policy-service agree

[Copilot]

Pull request overview

Adds a new aspnet-openapi skill to the dotnet-aspnet plugin to guide ASP.NET Core OpenAPI setup and migration (built-in Microsoft.AspNetCore.OpenApi vs Swashbuckle/NSwag), with supporting reference docs and eval scenarios.

Changes:

• Added aspnet-openapi skill documentation with end-to-end setup guidance (Scalar/Swagger UI), endpoint annotation patterns, JWT security scheme via transformers, and production-hardening guidance.
• Added reference docs covering transformer/filter equivalents and a Swashbuckle→built-in migration walkthrough.
• Added an eval suite with 4 scenarios to validate common OpenAPI setup/migration behaviors and pitfalls.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
tests/dotnet-aspnet/aspnet-openapi/eval.yaml	Adds eval scenarios for built-in OpenAPI + Scalar, Swashbuckle empty-spec pitfall, JWT scheme transformer, and migration flow.
plugins/dotnet-aspnet/skills/aspnet-openapi/SKILL.md	New primary skill workflow doc for OpenAPI technology selection, setup, UI integration, transformers, and securing spec endpoints.
plugins/dotnet-aspnet/skills/aspnet-openapi/references/transformers.md	Reference patterns for document/operation/schema transformers and Swashbuckle filter equivalents.
plugins/dotnet-aspnet/skills/aspnet-openapi/references/swashbuckle-migration.md	Step-by-step migration guide including mapping table and post-migration troubleshooting.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[raihanmehran]

@copilot review this PR