dotnet-openapi

name	dotnet-openapi
category	web
subcategory	minimal-apis
description	Generates OpenAPI docs. MS.AspNetCore.OpenApi (.NET 9+), Swashbuckle migration, NSwag.
license	MIT
targets	["*"]
tags	["api","dotnet","skill"]
version	0.0.1
author	dotnet-agent-harness
invocable	true
claudecode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
codexcli	{"short-description":".NET skill guidance for api tasks"}
opencode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
copilot	{}
geminicli	{}
antigravity	{}

dotnet-openapi

OpenAPI/Swagger integration for ASP.NET Core. Microsoft.AspNetCore.OpenApi is the recommended first-party approach for .NET 9+ and is the default in new project templates. Swashbuckle is no longer actively maintained; existing projects using Swashbuckle should plan migration. NSwag remains an alternative for client generation and advanced scenarios.

Scope

• Microsoft.AspNetCore.OpenApi setup and multi-document configuration
• Document, operation, and schema transformers
• Swashbuckle migration steps and filter-to-transformer mapping
• NSwag document generation and client generation
• OpenAPI 3.1 support in .NET 10

Out of scope

• Minimal API endpoint patterns (route groups, filters, TypedResults) -- see [skill:dotnet-minimal-apis]
• API versioning strategies -- see [skill:dotnet-api-versioning]
• Authentication and authorization -- see [skill:dotnet-api-security]

Cross-references: [skill:dotnet-minimal-apis] for endpoint patterns that generate OpenAPI metadata, [skill:dotnet-api-versioning] for versioned OpenAPI documents.

---

Microsoft.AspNetCore.OpenApi (Recommended)

Microsoft.AspNetCore.OpenApi is the first-party OpenAPI package for ASP.NET Core 9+ and is included by default in new project templates. .NET 10 adds OpenAPI 3.1 support with JSON Schema draft 2020-12 compliance.

Basic Setup

// Microsoft.AspNetCore.OpenApi -- included by default in .NET 9+ project templates
// If not present, add: <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.*" />
// Version must match the project's target framework major version

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi(); // Serves /openapi/v1.json
}

```json

### Multiple Documents

Generate separate OpenAPI documents per API version or functional group:

```csharp

builder.Services.AddOpenApi("v1", options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
});

builder.Services.AddOpenApi("v2", options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1;
});

var app = builder.Build();
app.MapOpenApi(); // Serves /openapi/v1.json and /openapi/v2.json

```json

---



Document transformers modify the generated OpenAPI document after it  built. Use them to  server information, security schemes,  custom metadata.



```csharp

    : 
{
    
    {
        document.Components ??=  OpenApiComponents();
        document.Components.SecuritySchemes[] =  OpenApiSecurityScheme
        {
            Type = SecuritySchemeType.Http,
            Scheme = ,
            BearerFormat = ,
            Description = 
        };

        document.SecurityRequirements.Add( OpenApiSecurityRequirement
        {
            [] = Array.Empty<>()
        });

         Task.CompletedTask;
    }
}


builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer<SecuritySchemeTransformer>();
});

```text



For simple transformations, use the lambda overload:

```csharp

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, ct) =>
    {
        document.Info =  OpenApiInfo
        {
            Title = ,
            Version = ,
            Description = ,
            Contact =  OpenApiContact
            {
                Name = ,
                Email = 
            }
        };
         Task.CompletedTask;
    });
});

```text

---




{
    
    {
         deprecatedAttr = context.Description.ActionDescriptor
            .EndpointMetadata
            .OfType<ObsoleteAttribute>()
            .FirstOrDefault();

         (deprecatedAttr   )
        {
            operation.Deprecated = ;
            operation.Description = ;
        }

         Task.CompletedTask;
    }
}

builder.Services.AddOpenApi(options =>
{
    options.AddOperationTransformer<DeprecationTransformer>();
});

```text

---



Customize how .NET types map to OpenAPI schemas  schema transformers:

```csharp

builder.Services.AddOpenApi(options =>
{
    options.AddSchemaTransformer((schema, context, ct) =>
    {
        
         (context.JsonTypeInfo.Type == (ProductDto))
        {
            schema.Example =  OpenApiObject
            {
                [] =  OpenApiInteger(),
                [] =  OpenApiString(),
                [] =  OpenApiDouble()
            };
        }
         Task.CompletedTask;
    });
});

```text



Use fluent methods  endpoint builders to provide richer OpenAPI metadata:

```csharp

products.MapGet(, GetProductById)
    .WithName()
    .WithSummary()
    .WithDescription()
    .WithTags()
    .Produces<Product>(StatusCodes.Status200OK)
    .ProducesProblem(StatusCodes.Status404NotFound);

```text

---



Swashbuckle (`Swashbuckle.AspNetCore`)  no longer actively maintained. It does  support OpenAPI . Existing projects should plan migration to `Microsoft.AspNetCore.OpenApi`.

**When Swashbuckle  still needed:** Projects  .NET  that cannot upgrade to .NET +,  projects that depend  Swashbuckle-= Version= /> -->
<!-- <PackageReference Include= Version= /> -->

```xml

 Replace service registration:

```csharp


builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc(,  OpenApiInfo { Title = , Version =  });
});


builder.Services.AddOpenApi();

```text

 Replace middleware:

```csharp


app.UseSwagger();
app.UseSwaggerUI();


app.MapOpenApi(); 

```json

 For Swagger UI,  a standalone UI package  use Scalar:

```csharp



app.MapScalarApiReference(); 



app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint(, );
});

```json

 Migrate Swashbuckle filters to transformers:

| Swashbuckle concept | Built- replacement |
|---------------------|---------------------|
| `IDocumentFilter` | `IOpenApiDocumentTransformer` |
| `IOperationFilter` | `IOpenApiOperationTransformer` |
| `ISchemaFilter` | Schema transformers via `AddSchemaTransformer` |
| `[SwaggerOperation]` | `.WithSummary()`, `.WithDescription()` |
| `[SwaggerResponse]` | `.Produces<T>()`, `TypedResults` |

---



NSwag  an alternative OpenAPI toolchain that includes document generation, ;

 app = builder.Build();
app.UseOpenApi();    
app.UseSwaggerUi(); 

```json



NSwag generates typed C

```bash


dotnet tool install -- NSwag.ConsoleCore


nswag openapi2csclient /input:https:
    /output:GeneratedClient.cs \
    /: \
    /:

```

**:**  ``   .             .           .

---

##  3.1 (. 10)

. 10    3.1      2020-12 .    3.0:

- ** :**    `: ["", ""]`   `: `
- ** :**  /    
- **:** -  
- **  :**       2020-12 

```



( =>
{
    
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1;
});

```text

**Gotcha:** Swashbuckle does  support OpenAPI . Projects requiring  features must migrate to `Microsoft.AspNetCore.OpenApi`.

---



 **Do  pin mismatched major versions of `Microsoft.AspNetCore.OpenApi`** -- the package version must match the project