Skip to content

overview.md

Latest commit

 

History

History
78 lines (51 loc) · 4.09 KB

overview.md

File metadata and controls

78 lines (51 loc) · 4.09 KB
title Overview of OpenAPI support in ASP.NET Core API apps
ai-usage ai-assisted
author wadepickett
description Learn how to integrate OpenAPI in ASP.NET Core API apps. Discover features, tools, and packages for generating and customizing OpenAPI documents.
monikerRange >= aspnetcore-6.0
ms.author wpickett
ms.reviewer wpickett
ms.date 03/20/2026
uid fundamentals/openapi/overview

OpenAPI support in ASP.NET Core API apps

[!INCLUDE]

:::moniker range=">= aspnetcore-10.0"

ASP.NET Core supports the generation of OpenAPI documents in controller-based and Minimal API apps. The OpenAPI specification is a programming language-agnostic standard for documenting HTTP APIs. ASP.NET Core apps support this standard through a combination of built-in APIs and open-source libraries. There are three key aspects to OpenAPI integration in an application:

  • Generating information about the endpoints in the app.
  • Gathering the information into a format that matches the OpenAPI schema.
  • Exposing the generated OpenAPI document through a visual UI or a serialized file.

ASP.NET Core provides first-party support for generating information about endpoints in an app through the Microsoft.AspNetCore.OpenApi package.

The ASP.NET Core minimal web API template generates the following code that uses OpenAPI:

[!code-csharp]

In the preceding highlighted code:

  • AddOpenApi registers services required for OpenAPI document generation into the application's DI container.
  • MapOpenApi adds an endpoint into the application for viewing the OpenAPI document serialized into JSON. The OpenAPI endpoint is restricted to the Development environment to minimize the risk of exposing sensitive information and reduce the vulnerabilities in production.

Microsoft.AspNetCore.OpenApi NuGet package

The Microsoft.AspNetCore.OpenApi package provides the following features:

  • Support for generating OpenAPI documents at runtime and accessing them through an endpoint on the application.
  • Support for "transformer" APIs that modify the generated document.

To use the Microsoft.AspNetCore.OpenApi package, add it as a PackageReference to a project file:

[!code-xml]

To learn more about the Microsoft.AspNetCore.OpenApi package, see xref:fundamentals/openapi/aspnetcore-openapi.

Microsoft.Extensions.ApiDescription.Server NuGet package

The Microsoft.Extensions.ApiDescription.Server package supports generating OpenAPI documents at build time and serializing them.

To use Microsoft.Extensions.ApiDescription.Server, add it as a PackageReference to a project file. Enable document generation at build time by setting the OpenApiGenerateDocuments property. By default, the generated OpenAPI document is saved to the obj directory, but you can customize the output directory by setting the OpenApiDocumentsDirectory property.

[!code-xml]

[!INCLUDE]

ASP.NET Core OpenAPI source code on GitHub

Additional Resources

  • xref:fundamentals/minimal-apis/security

:::moniker-end

[!INCLUDE] [!INCLUDE]