Built-in OpenAPI support for .NET 10 applications. Covers document generation, transformers, TypedResults metadata, security schemes, XML comments, build-time generation, and multiple document support. No Swashbuckle needed. Load this skill when setting up API documentation, customizing OpenAPI outp

OpenAPI Core Principles 1. Built in, not Swashbuckle — .NET 10 ships Microsoft.AspNetCore.OpenApi as the official, framework maintained OpenAPI solution. Swashbuckle was removed from templates in .NET 9 and is no longer recommended. 2. TypedResults drive the schema — TypedResults.Ok<T () automatically generates correct OpenAPI response schemas. Results.Ok() does not. Always use TypedResults . 3. Transformers over workarounds — Document, operation, and schema transformers compose cleanly. Use them for security schemes, global responses, and schema customization. 4. Metadata on every endpoint — Use .WithName() , .WithSummary() , .WithTags() on every endpoint. This metadata feeds directly into the OpenAPI spec and client generators. Patterns Basic Setup Endpoint Metadata With TypedResults , response metadata is inferred automatically: Bearer Token Security Scheme Document Info Transformer Multiple OpenAPI Documents Endpoints without .WithGroupName() appear in all documents. XML Documentation Comments (.NET 10) Enable in the project file — the source generator extracts <summary , <param , <response tags automatically: XML comments on lambdas are not captured by the compiler. Use named methods. Schema Transformer Per Endpoint Operation Transformer (.NET 10) Build Time Document Generation The spec file is generated in the output directory during build. YAML Endpoint (.NET 10) Anti patterns Don't Use Swashbuckle for New Projects Don't Use WithOpenApi() in .NET 10 Don't Use Untyped Results Don't Skip WithName on Endpoints Don't Use OpenApiAny in .NET 10 Decision Guide Scenario Recommendation New API project AddOpenApi() + MapOpenApi() (built in) API documentation UI Scalar ( MapScalarApiReference() ) Security schemes in docs Document transformer with IOpenApiDocumentTransformer Response documentation TypedResults with union return types XML doc integration <GenerateDocumentationFile true</GenerateDocumentationFile Multiple API versions Multiple AddOpenApi("v1") calls + WithGroupName() Client code generation Kiota (Microsoft recommended) or NSwag Build time spec Microsoft.Extensions.ApiDescription.Server package OpenAPI version 3.1 (default in .NET 10), force 3.0 if consumers require it Per endpoint customization .AddOpenApiOperationTransformer() on the endpoint

openapi