Skip to content

Commit

Permalink
What's new OpenAPI (#32616)
Browse files Browse the repository at this point in the history
* What's new OpenAPI

* What's new OpenAPI

* What's new OpenAPI

* What's new OpenAPI

* What's new OpenAPI

* What's new OpenAPI
  • Loading branch information
Rick-Anderson authored May 21, 2024
1 parent 3fb82eb commit acfdf45
Show file tree
Hide file tree
Showing 8 changed files with 89 additions and 1 deletion.
6 changes: 5 additions & 1 deletion aspnetcore/release-notes/aspnetcore-9.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ author: rick-anderson
description: Learn about the new features in ASP.NET Core 9.0.
ms.author: riande
ms.custom: mvc
ms.date: 05/20/2024
ms.date: 5/20/2024
uid: aspnetcore-9
---
# What's new in ASP.NET Core 9.0
Expand Down Expand Up @@ -33,6 +33,10 @@ This section describes new features for minimal APIs.

[!INCLUDE[](~/release-notes/aspnetcore-9/includes/status500.md)]

## OpenAPI

[!INCLUDE[](~/release-notes/aspnetcore-9/includes/openApi.md)]

## Authentication and authorization

This section describes new features for authentication and authorization.
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
38 changes: 38 additions & 0 deletions aspnetcore/release-notes/aspnetcore-9/includes/openApi.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
### Built-in support for OpenAPI document generation

The [OpenAPI specification](https://www.openapis.org/) is a standard for describing HTTP APIs. The standard allows developers to define the shape of APIs that can be plugged into client generators, server generators, testing tools, documentation, and more. In .NET 9 Preview, ASP.NET Core provides built-in support for generating OpenAPI documents representing controller-based or minimal APIs via the [Microsoft.AspNetCore.OpenApi](https://nuget.org/packages/Microsoft.AspNetCore.OpenApi) package.

The following highlighted code calls:

- `AddOpenApi` to register the required dependencies into the app's DI container.
- `MapOpenApi` to register the required OpenAPI endpoints in the app's routes.

:::code language="csharp" source="~/release-notes/aspnetcore-9/samples/OpenApiExample/Program.cs" highlight="3,7":::

Install the [`Microsoft.AspNetCore.OpenApi`](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi/9.0.0) package in the project using the following command:

```console
dotnet add package Microsoft.AspNetCore.OpenApi --prerelease
```

Run the app and navigate to `openapi/v1.json` to view the generated OpenAPI document:

![OpenAPI document](~/release-notes/aspnetcore-9/_static/OpenApiDoc.png)

OpenAPI documents can also be generated at build-time by adding the [`Microsoft.Extensions.ApiDescription.Server`](https://www.nuget.org/packages/Microsoft.Extensions.ApiDescription.Server) package:

```console
dotnet add package Microsoft.Extensions.ApiDescription.Server --prerelease
```

In the app's project file, add the following:

:::code language="xml" source="~/release-notes/aspnetcore-9/samples/OpenApiExample/OpenApiExample.csproj" range="9-12":::

Run `dotnet build` and inspect the generated JSON file in the project directory.

![OpenAPI document generation at build-time](~/release-notes/aspnetcore-9/_static/openapidoc2.png)

ASP.NET Core's built-in OpenAPI document generation provides support for various customizations and options, including document and operation transformers and the ability to manage multiple OpenAPI documents for the same application.

To learn more about ASP.NET Core's new OpenAPI document capabilities, see [the new Microsoft.AspNetCore.OpenApi docs](https://aka.ms/aspnet/openapi).
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<Project Sdk="Microsoft.NET.Sdk.Web">

<PropertyGroup>
<TargetFramework>net9.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

<PropertyGroup>
<OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.0-preview.5" />
</ItemGroup>

</Project>
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/hello/{name}", (string name) => $"Hello {name}"!);

app.Run();
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*"
}

0 comments on commit acfdf45

Please sign in to comment.