-
Notifications
You must be signed in to change notification settings - Fork 25.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 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
1 parent
3fb82eb
commit acfdf45
Showing
8 changed files
with
89 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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). |
18 changes: 18 additions & 0 deletions
18
aspnetcore/release-notes/aspnetcore-9/samples/OpenApiExample/OpenApiExample.csproj
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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> |
11 changes: 11 additions & 0 deletions
11
aspnetcore/release-notes/aspnetcore-9/samples/OpenApiExample/Program.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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(); |
8 changes: 8 additions & 0 deletions
8
aspnetcore/release-notes/aspnetcore-9/samples/OpenApiExample/appsettings.Development.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
{ | ||
"Logging": { | ||
"LogLevel": { | ||
"Default": "Information", | ||
"Microsoft.AspNetCore": "Warning" | ||
} | ||
} | ||
} |
9 changes: 9 additions & 0 deletions
9
aspnetcore/release-notes/aspnetcore-9/samples/OpenApiExample/appsettings.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
{ | ||
"Logging": { | ||
"LogLevel": { | ||
"Default": "Information", | ||
"Microsoft.AspNetCore": "Warning" | ||
} | ||
}, | ||
"AllowedHosts": "*" | ||
} |