Add aspnet-openapi skill (#dotnet-aspnet) by raihanmehran · Pull Request #486 · dotnet/skills

raihanmehran · 2026-03-31T14:55:41Z

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 · 2026-03-31T15:00:19Z

@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.

- Fully-qualify System.Reflection.Assembly in Swashbuckle XML docs snippet (Assembly.GetExecutingAssembly is not in default global usings) - Add 'using Microsoft.OpenApi.Models' to the transformer registration snippet in references/transformers.md (OpenApiContact/OpenApiInfo are not in default global usings)

…Swashbuckle enum filter bug

raihanmehran · 2026-04-01T07:18:01Z

@copilot review this PR

AbhitejJohn · 2026-05-22T00:08:48Z

Tagging @danroth27 for thoughts on this. Please feel free to loop in anyone else on the team who might be able to help as well.

danroth27 · 2026-05-22T15:54:00Z

Adding @mikekistler @Youssef1313 and @javiercn to take a look.

mikekistler

Thanks for this submission!

I left comments on a number of small issues that need to be addressed.

mikekistler · 2026-05-22T16:03:27Z

+- You need features the built-in package does not yet support (advanced polymorphism,
+  `oneOf`/`anyOf` discriminators, complex `$ref` scenarios)


Not sure what this is referring to. Built-in OpenAPI generation supports polymorphism, oneOf and anyOf schemas, and most complex $ref scenarios I'm aware of. I think more specific guidance is needed here.

mikekistler · 2026-05-22T16:06:26Z

+
+## Migrate or Stay?
+
+Migration is not mandatory. Swashbuckle continues to work on .NET 9+ with version 7.x.


The current latest version of Swashbuckle.AspNetCore is 10.1.7, and has many improvements over v7.x. Is this recommending against using packages more recent than 7.x? Maybe this should say "7.x or later"?

mikekistler · 2026-05-22T16:09:25Z

+<PackageReference Include="Swashbuckle.AspNetCore" Version="7.*" />
+
+<!-- Add -->
+<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.*" />


Is this skill .NET 9 specific? How do we write this in a way that makes it applicable to .NET 9 and later?

mikekistler · 2026-05-22T16:10:59Z

+<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.*" />
+
+<!-- If you still want Swagger UI instead of Scalar -->
+<PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="7.*" />


Here too, I think we should recommend the most recent version of washbuckle.AspNetCore.SwaggerUI.

Maybe we should be recommending a dotnet add package command, rather than specific updates to the csproj, so that the right levels are used automatically.

mikekistler · 2026-05-22T16:15:28Z

+| `context.ApiDescription` (in `IOperationFilter`) | `context.Description` | Same type: `ApiDescription` |
+
+### XML Documentation Note
+


I think metadata from XML doc comments was not added to ASP.NET Core until .NET 10. I think that should be mentioned here.

mikekistler · 2026-05-22T19:59:01Z

+For **minimal APIs**, XML comments on the handler delegate are not picked up
+automatically — use `.WithSummary()` and `.WithDescription()` on the endpoint
+instead (shown in SKILL.md Step 5). For **MVC controller actions**, XML `<summary>`


Recommend defining the delegate as a local method, as described above.

mikekistler · 2026-05-22T20:10:01Z

+By default, enums serialize as integers in the spec. To represent them as string values:
+
+```csharp
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi.Any;
+using Microsoft.OpenApi.Models;
+
+internal sealed class EnumSchemaTransformer : IOpenApiSchemaTransformer
+{
+    public Task TransformAsync(
+        OpenApiSchema schema,
+        OpenApiSchemaTransformerContext context,
+        CancellationToken cancellationToken)
+    {
+        if (context.JsonTypeInfo.Type.IsEnum)
+        {
+            schema.Type = "string";
+            schema.Enum = Enum.GetNames(context.JsonTypeInfo.Type)
+                .Select(name => new OpenApiString(name))
+                .Cast<IOpenApiAny>()
+                .ToList();
+        }
+
+        return Task.CompletedTask;
+    }
+}
+```
+
+> This transformer only affects the OpenAPI schema. Ensure your `JsonSerializerOptions`
+> (or `System.Text.Json` attributes) are also configured to serialize enums as strings at
+> runtime — the spec and the actual wire format must agree.


Replace this whole section with "use JsonStringEnumConverter.

mikekistler · 2026-05-22T20:15:53Z

+
+## Stop Signals
+
+- **Need to generate C# or TypeScript API clients?** — Use NSwag or `dotnet-openapi`. This skill covers spec *generation*, not *consumption*.


There are plenty of options for generating clients besides NSwag, for example Kiota, that take OpenAPI as input, so I don't think this is necessarily a "stop signal".

mikekistler · 2026-05-22T20:19:44Z

+| Need typed client code generation | `NSwag.AspNetCore` | Only mature option with C#/TypeScript codegen; pair with the spec output |
+| Complex polymorphism or discriminators | `NSwag.AspNetCore` | More schema control than either alternative |


Neither of these cases should recommend against using built-in OpenAPI doc generation.

mikekistler · 2026-05-22T20:23:47Z

+The spec is only as useful as the metadata you put in. Sparse annotations produce a sparse,
+useless spec — and waste the entire investment in Step 2–4.
+
+**Minimal APIs:**


This section should show an example with XML doc comments as the source of OpenAPI metadata.

Add aspnet-openapi skill to dotnet-aspnet plugin

03e5f98

raihanmehran requested review from BrennanConroy and adityamandaleeka as code owners March 31, 2026 14:55

Copilot AI review requested due to automatic review settings March 31, 2026 14:55

Copilot started reviewing on behalf of raihanmehran March 31, 2026 14:56 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

Comment thread plugins/dotnet-aspnet/skills/aspnet-openapi/SKILL.md Outdated

Comment thread plugins/dotnet-aspnet/skills/aspnet-openapi/SKILL.md Outdated

Comment thread plugins/dotnet-aspnet/skills/aspnet-openapi/references/swashbuckle-migration.md Outdated

Address Copilot PR review comments

a802f80

raihanmehran force-pushed the feat/aspnet-openapi-skill branch from 6e44be4 to a802f80 Compare March 31, 2026 15:20

raihanmehran requested a review from Copilot March 31, 2026 15:21

Copilot started reviewing on behalf of raihanmehran March 31, 2026 15:22 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

Comment thread plugins/dotnet-aspnet/skills/aspnet-openapi/SKILL.md Outdated

Comment thread plugins/dotnet-aspnet/skills/aspnet-openapi/references/transformers.md

raihanmehran requested a review from Copilot March 31, 2026 15:35

Copilot started reviewing on behalf of raihanmehran March 31, 2026 15:36 View session

Add missing using directives and context comment in transformer snippets

b4520f2

raihanmehran force-pushed the feat/aspnet-openapi-skill branch from b6cf426 to b4520f2 Compare April 1, 2026 06:54

nickmehran added 2 commits April 1, 2026 09:00

Fix Swashbuckle.AspNetCore.SwaggerUI package name casing

3d9c7f4

Fix inaccurate .NET version claims, pitfall table contradiction, and …

45dc0cf

…Swashbuckle enum filter bug

Merge branch 'main' into feat/aspnet-openapi-skill

083c7b6

github-actions Bot mentioned this pull request Apr 7, 2026

🏥 Repository Health Dashboard #288

Open

raihanmehran added 2 commits April 7, 2026 11:00

Merge branch 'main' into feat/aspnet-openapi-skill

11b85be

Merge branch 'main' into feat/aspnet-openapi-skill

efa719c

This was referenced Apr 13, 2026

Log exceptions in AgentRunner.StopAllClients catch block #349

Closed

Add --run-in-docker to skill-validator to run Copilot CLI in a docker container #273

Closed

This was referenced Apr 27, 2026

Add F# support to migrate-dotnet* skills #406

Closed

Add dotnet-fsharp plugin #302

Closed

This was referenced May 4, 2026

Fall back to rubric scores when pairwise judge is position-swap-inconsistent #475

Closed

Add setup-local-sdk skill for global.json paths feature #508

Open

github-actions Bot mentioned this pull request May 11, 2026

feat: skill loading tests #311

Closed

AbhitejJohn added waiting-on-review PR state label area-aspnet labels May 21, 2026

danroth27 requested review from Youssef1313, javiercn and mikekistler May 22, 2026 15:51

mikekistler suggested changes May 22, 2026

View reviewed changes

github-actions Bot mentioned this pull request May 25, 2026

Add Codex-native plugin marketplace manifest #555

Open

		- You need features the built-in package does not yet support (advanced polymorphism,
		`oneOf`/`anyOf` discriminators, complex `$ref` scenarios)


		## Migrate or Stay?

		Migration is not mandatory. Swashbuckle continues to work on .NET 9+ with version 7.x.

		\| `context.ApiDescription` (in `IOperationFilter`) \| `context.Description` \| Same type: `ApiDescription` \|

		### XML Documentation Note


		## Stop Signals

		- Need to generate C# or TypeScript API clients? — Use NSwag or `dotnet-openapi`. This skill covers spec generation, not consumption.

		\| Need typed client code generation \| `NSwag.AspNetCore` \| Only mature option with C#/TypeScript codegen; pair with the spec output \|
		\| Complex polymorphism or discriminators \| `NSwag.AspNetCore` \| More schema control than either alternative \|

Conversation

raihanmehran commented Mar 31, 2026

Summary

What's included

Motivation

Uh oh!

raihanmehran commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

raihanmehran commented Apr 1, 2026

Uh oh!

AbhitejJohn commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

danroth27 commented May 22, 2026

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

AbhitejJohn commented May 22, 2026 •

edited

Loading