Skip to content

Commit 2684252

Browse files
Rick-AndersonRick-Anderson
authored
Merge pull request #34343 from dotnet/main
Merge to Live
2 parents 016a23b + be0dc41 commit 2684252

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+61317
-44
lines changed

‎aspnetcore/fundamentals/openapi/aspnetcore-openapi.md‎

Lines changed: 37 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Learn how to generate and customize OpenAPI documents in an ASP.NET
55
ms.author: safia
66
monikerRange: '>= aspnetcore-6.0'
77
ms.custom: mvc
8-
ms.date: 09/05/2024
8+
ms.date: 12/11/2024
99
uid: fundamentals/openapi/aspnetcore-openapi
1010
---
1111
# Generate OpenAPI documents
@@ -188,26 +188,49 @@ Some applications may be configured to emit multiple OpenAPI documents, for vari
188188

189189
### Customizing run-time behavior during build-time document generation
190190

191-
Under the hood, build-time OpenAPI document generation functions by launching the application's entrypoint with an inert server implementation. This is a requirement to produce accurate OpenAPI documents since all information in the OpenAPI document cannot be statically analyzed. Because the application's entrypoint is invoked, any logic in the applications' startup will be invoked. This includes code that injects services into the DI container or reads from configuration. In some scenarios, it's necessary to restrict the codepaths that will run when the application's entry point is being invoked from build-time document generation. These scenarios include:
191+
Build-time OpenAPI document generation functions by launching the apps entrypoint with a mock server implementation. A mock server is required to produce accurate OpenAPI documents because all information in the OpenAPI document can't be statically analyzed. Because the apps entrypoint is invoked, any logic in the apps startup is invoked. This includes code that injects services into the [DI container](xref:fundamentals/dependency-injection) or reads from configuration. In some scenarios, it's necessary to restrict the code paths that will run when the apps entry point is being invoked from build-time document generation. These scenarios include:
192192

193-
- Not reading from certain configuration strings.
194-
- Not registering database-related services.
193+
* Not reading from certain configuration strings.
194+
* Not registering database-related services.
195195

196-
In order to restrict these codepaths from being invoked by the build-time generation pipeline, they can be conditioned behind a check of the entry assembly like so:
196+
In order to restrict these code paths from being invoked by the build-time generation pipeline, they can be conditioned behind a check of the entry assembly:
197197

198-
```csharp
199-
using System.Reflection;
198+
:::code language="csharp" source="~/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.Web/Program.cs" highlight="5-8":::
200199

201-
var builder = WebApplication.CreateBuilder();
200+
[AddServiceDefaults](https://source.dot.net/#TestingAppHost1.ServiceDefaults/Extensions.cs,0f0d863053754768,references) Adds common .NET Aspire services such as service discovery, resilience, health checks, and OpenTelemetry.
202201

203-
if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
204-
{
205-
builder.Services.AddDefaults();
206-
}
202+
:::moniker-end
203+
204+
## Trimming and Native AOT
205+
206+
OpenAPI in ASP.NET Core supports trimming and native AOT. The following steps create and publish an OpenAPI app with trimming and native AOT:
207+
208+
Create a new ASP.NET Core Web API (Native AOT) project.
209+
210+
```console
211+
dotnet new webapiaot
207212
```
208213

209-
::: moniker-end
214+
Add the Microsoft.AspNetCore.OpenAPI package.
210215

211-
[!INCLUDE[](~/fundamentals/openapi/includes/aspnetcore-openapi6-8.md)]
216+
```console
217+
dotnet add package Microsoft.AspNetCore.OpenApi --prerelease
218+
```
212219

220+
Update `Program.cs` to enable generating OpenAPI documents.
213221

222+
```diff
223+
+ builder.Services.AddOpenApi();
224+
225+
var app = builder.Build();
226+
227+
+ app.MapOpenApi();
228+
```
229+
230+
Publish the app.
231+
232+
```console
233+
dotnet publish
234+
```
235+
236+
[!INCLUDE[](~/fundamentals/openapi/includes/aspnetcore-openapi6-8.md)]

‎aspnetcore/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.ApiService/AspireApp1.ApiService.csproj‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<Project Sdk="Microsoft.NET.Sdk.Web">
2+
3+
<PropertyGroup>
4+
<TargetFramework>net9.0</TargetFramework>
5+
<ImplicitUsings>enable</ImplicitUsings>
6+
<Nullable>enable</Nullable>
7+
</PropertyGroup>
8+
9+
<ItemGroup>
10+
<ProjectReference Include="..\AspireApp1.ServiceDefaults\AspireApp1.ServiceDefaults.csproj" />
11+
</ItemGroup>
12+
13+
<ItemGroup>
14+
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.0" />
15+
</ItemGroup>
16+
17+
</Project>

‎aspnetcore/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.ApiService/Program.cs‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
var builder = WebApplication.CreateBuilder(args);
2+
3+
// Add service defaults & Aspire client integrations.
4+
builder.AddServiceDefaults();
5+
6+
// Add services to the container.
7+
builder.Services.AddProblemDetails();
8+
9+
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
10+
builder.Services.AddOpenApi();
11+
12+
var app = builder.Build();
13+
14+
// Configure the HTTP request pipeline.
15+
app.UseExceptionHandler();
16+
17+
if (app.Environment.IsDevelopment())
18+
{
19+
app.MapOpenApi();
20+
}
21+
22+
string[] summaries = ["Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"];
23+
24+
app.MapGet("/weatherforecast", () =>
25+
{
26+
var forecast = Enumerable.Range(1, 5).Select(index =>
27+
new WeatherForecast
28+
(
29+
DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
30+
Random.Shared.Next(-20, 55),
31+
summaries[Random.Shared.Next(summaries.Length)]
32+
))
33+
.ToArray();
34+
return forecast;
35+
})
36+
.WithName("GetWeatherForecast");
37+
38+
app.MapDefaultEndpoints();
39+
40+
app.Run();
41+
42+
record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
43+
{
44+
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
45+
}

‎aspnetcore/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.ApiService/appsettings.Development.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"Logging": {
3+
"LogLevel": {
4+
"Default": "Information",
5+
"Microsoft.AspNetCore": "Warning"
6+
}
7+
}
8+
}

‎aspnetcore/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.ApiService/appsettings.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"Logging": {
3+
"LogLevel": {
4+
"Default": "Information",
5+
"Microsoft.AspNetCore": "Warning"
6+
}
7+
},
8+
"AllowedHosts": "*"
9+
}

‎aspnetcore/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.AppHost/AspireApp1.AppHost.csproj‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />
4+
5+
<PropertyGroup>
6+
<OutputType>Exe</OutputType>
7+
<TargetFramework>net9.0</TargetFramework>
8+
<ImplicitUsings>enable</ImplicitUsings>
9+
<Nullable>enable</Nullable>
10+
<IsAspireHost>true</IsAspireHost>
11+
<UserSecretsId>f8d592cd-16b9-4fe6-a662-9bcaeca80677</UserSecretsId>
12+
</PropertyGroup>
13+
14+
<ItemGroup>
15+
<ProjectReference Include="..\AspireApp1.ApiService\AspireApp1.ApiService.csproj" />
16+
<ProjectReference Include="..\AspireApp1.Web\AspireApp1.Web.csproj" />
17+
</ItemGroup>
18+
19+
<ItemGroup>
20+
<PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
21+
</ItemGroup>
22+
23+
</Project>

‎aspnetcore/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.AppHost/Program.cs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
var builder = DistributedApplication.CreateBuilder(args);
2+
3+
var apiService = builder.AddProject<Projects.AspireApp1_ApiService>("apiservice");
4+
5+
builder.AddProject<Projects.AspireApp1_Web>("webfrontend")
6+
.WithExternalHttpEndpoints()
7+
.WithReference(apiService)
8+
.WaitFor(apiService);
9+
10+
builder.Build().Run();

‎aspnetcore/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.AppHost/appsettings.Development.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"Logging": {
3+
"LogLevel": {
4+
"Default": "Information",
5+
"Microsoft.AspNetCore": "Warning"
6+
}
7+
}
8+
}

‎aspnetcore/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.AppHost/appsettings.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"Logging": {
3+
"LogLevel": {
4+
"Default": "Information",
5+
"Microsoft.AspNetCore": "Warning",
6+
"Aspire.Hosting.Dcp": "Warning"
7+
}
8+
}
9+
}

‎aspnetcore/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.ServiceDefaults/AspireApp1.ServiceDefaults.csproj‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<TargetFramework>net9.0</TargetFramework>
5+
<ImplicitUsings>enable</ImplicitUsings>
6+
<Nullable>enable</Nullable>
7+
<IsAspireSharedProject>true</IsAspireSharedProject>
8+
</PropertyGroup>
9+
10+
<ItemGroup>
11+
<FrameworkReference Include="Microsoft.AspNetCore.App" />
12+
13+
<PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="9.0.0" />
14+
<PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.0.0" />
15+
<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
16+
<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
17+
<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
18+
<PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
19+
<PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.9.0" />
20+
</ItemGroup>
21+
22+
</Project>

0 commit comments

Comments
 (0)