From df659298849954b91ccb1a4effc4b9a36e711a47 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 10:52:13 -1000 Subject: [PATCH 01/71] Fix and Edit build time OpenAPI/ra --- .../openapi/aspnetcore-openapi.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md index 0f6d921ddb9b..93c8e945d51a 100644 --- a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md +++ b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md @@ -67,7 +67,7 @@ The following code: * Adds OpenAPI services. * Enables the endpoint for viewing the OpenAPI document in JSON format. -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_first&highlight=3,7)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_first&highlight=3,7)] Launch the app and navigate to `https://localhost:/openapi/v1.json` to view the generated OpenAPI document. @@ -400,13 +400,13 @@ Because the OpenAPI document is served via a route handler endpoint, any customi The OpenAPI endpoint doesn't enable any authorization checks by default. However, it's possible to limit access to the OpenAPI document. For example, in the following code, access to the OpenAPI document is limited to those with the `tester` role: -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_mapopenapiwithauth)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_mapopenapiwithauth)] #### Cache generated OpenAPI document The OpenAPI document is regenerated every time a request to the OpenAPI endpoint is sent. Regeneration enables transformers to incorporate dynamic application state into their operation. For example, regenerating a request with details of the HTTP context. When applicable, the OpenAPI document can be cached to avoid executing the document generation pipeline on each HTTP request. -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_mapopenapiwithcaching)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_mapopenapiwithcaching)] @@ -434,13 +434,13 @@ Transformers can be registered onto the document via the `AddDocumentTransformer * Register a document transformer using a DI-activated `IOpenApiDocumentTransformer`. * Register an operation transformer using a delegate. -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_transUse&highlight=8-13)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_transUse&highlight=8-13)] ### Execution order for transformers Transformers execute in first-in first-out order based on registration. In the following snippet, the document transformer has access to the modifications made by the operation transformer: -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_transInOut&highlight=3-9)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_transInOut&highlight=3-9)] ### Use document transformers @@ -452,18 +452,18 @@ Document transformers have access to a context object that includes: Document transformers also can mutate the OpenAPI document that is generated. The following example demonstrates a document transformer that adds some information about the API to the OpenAPI document. -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_documenttransformer1)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_documenttransformer1)] Service-activated document transformers can utilize instances from DI to modify the app. The following sample demonstrates a document transformer that uses the `IAuthenticationSchemeProvider` service from the authentication layer. It checks if any JWT bearer-related schemes are registered in the app and adds them to the OpenAPI document's top level: -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_documenttransformer2)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_documenttransformer2)] Document transformers are unique to the document instance they're associated with. In the following example, a transformer: * Registers authentication-related requirements to the `internal` document. * Leaves the `public` document unmodified. -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_multidoc_operationtransformer1)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_multidoc_operationtransformer1)] ### Use operation transformers @@ -480,7 +480,7 @@ Operation transformers have access to a context object which contains: For example, the following operation transformer adds `500` as a response status code supported by all operations in the document. -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_operationtransformer1)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_operationtransformer1)] ## Using the generated OpenAPI document @@ -494,13 +494,13 @@ The `Swashbuckle.AspNetCore.SwaggerUi` package provides a bundle of Swagger UI's Enable the swagger-ui middleware with a reference to the OpenAPI route registered earlier. To limit information disclosure and security vulnerability, ***only enable Swagger UI in development environments.*** -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_swaggerui)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_swaggerui)] ### Using Scalar for interactive API documentation [Scalar](https://scalar.com/) is an open-source interactive document UI for OpenAPI. Scalar can integrate with the OpenAPI endpoint provided by ASP.NET Core. To configure Scalar, install the `Scalar.AspNetCore` package. -[!code-csharp[](~/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs?name=snippet_openapiwithscalar)] +[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_openapiwithscalar)] ### Lint generated OpenAPI documents with Spectral From 42711fc44f1e0d6d5aaeb776780c414a69fa1025 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 11:34:07 -1000 Subject: [PATCH 02/71] Fix and Edit build time OpenAPI/ra --- .../openapi/aspnetcore-openapi.md | 2 + .../fundamentals/openapi/buildtime-openapi.md | 40 +++++++++++-------- 2 files changed, 25 insertions(+), 17 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md index 93c8e945d51a..031210ce6a29 100644 --- a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md +++ b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md @@ -8,6 +8,8 @@ ms.custom: mvc ms.date: 5/22/2024 uid: fundamentals/openapi/aspnetcore-openapi --- + + # Work with OpenAPI documents :::moniker range=">= aspnetcore-9.0" diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 5fbf081b8483..371d0e832f16 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -8,18 +8,19 @@ ms.custom: mvc ms.date: 8/13/2024 uid: fundamentals/openapi/buildtime-openapi --- + # Generate OpenAPI documents at build-time -In a typical web applications, OpenAPI documents are generated at run-time and served via an HTTP request to the application server. +In a typical web apps, OpenAPI documents are generated at run-time and served via an HTTP request to the app server. -In some scenarios, it is helpful to generate the OpenAPI document during the application's build step. These scenarios including: +Generating OpenAPI documentation during the app's build step can be useful for documentation that is: -- Generating OpenAPI documentation that is committed into source control -- Generating OpenAPI documentation that is used for spec-based integration testing -- Generating OpenAPI documentation that is served statically from the web server +- Committed into source control +- Used for spec-based integration testing +- Served statically from the web server -To add support for generating OpenAPI documents at build time, install the `Microsoft.Extensions.ApiDescription.Server` package: +To add support for generating OpenAPI documents at build time, install the [`Microsoft.Extensions.ApiDescription.Server`](https://www.nuget.org/packages/Microsoft.Extensions.ApiDescription.Server) NuGet package: ### [Visual Studio](#tab/visual-studio) @@ -38,18 +39,18 @@ dotnet add package Microsoft.Extensions.ApiDescription.Server --prerelease ``` --- -Upon installation, this package will automatically generate the Open API document(s) associated with the application during build and populate them into the application's output directory. +This package automatically generates the Open API document(s) associated with the app during build and populates them into the app's output directory. ```cli $ dotnet build $ cat bin/Debub/net9.0/{ProjectName}.json ``` -## Customizing build-time document generation +## Customize build-time document generation -### Modifying the output directory of the generated Open API file +### Modify the output directory of the generated Open API file -By default, the generated OpenAPI document will be emitted to the application's output directory. To modify the location of the emitted file, set the target path in the `OpenApiDocumentsDirectory` property. +By default, the generated OpenAPI document is generated in the app's output directory. To modify the location of the generated file, set the target path in the `OpenApiDocumentsDirectory` property in the project file: ```xml @@ -57,11 +58,11 @@ By default, the generated OpenAPI document will be emitted to the application's ``` -The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `./` value above will emit the OpenAPI document in the same directory as the project file. +The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `./` value in the preceding markup generates the OpenAPI document in the same directory as the project file. -### Modifying the output file name +### Modify the output file name -By default, the generated OpenAPI document will have the same name as the application's project file. To modify the name of the emitted file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property. +By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the generated file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property: ```xml @@ -69,9 +70,14 @@ By default, the generated OpenAPI document will have the same name as the applic ``` -### Selecting the OpenAPI document to generate +### Select the OpenAPI document to generate -Some applications may be configured to emit multiple OpenAPI documents, for various versions of an API or to distinguish between public and internal APIs. By default, the build-time document generator will emit files for all documents that are configured in an application. To only emit for a single document name, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property. +Some apps may be configured to generate multiple OpenAPI documents, for example: + +* For various versions of an API. +* To distinguish between public and internal APIs. + +By default, the build-time document generator generates files for all documents that are configured in an app. To generate for a single document name only, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property: ```xml @@ -79,9 +85,9 @@ Some applications may be configured to emit multiple OpenAPI documents, for vari ``` -## Customizing run-time behavior during build-time document generation +## Customize run-time behavior during build-time document generation -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: +The OpenAPI document generation at build-time works by starting the app’s entrypoint with a temporary background server. This is a requirement to produce accurate OpenAPI documents because all information in the OpenAPI document can't be statically analyzed. Because the app's entrypoint is invoked, any logic in the apps' 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 app's entry point is being invoked from build-time document generation. These scenarios include: - Not reading from certain configuration strings - Not registering database-related services From 1649587e8e52187a39883fa7fbd8a4616b92a9a5 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 12:00:56 -1000 Subject: [PATCH 03/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 8 ++-- .../samples/9.x/BuildTime/MyTestApi.csproj | 18 +++++++++ .../samples/9.x/BuildTime/MyTestApi.http | 6 +++ .../openapi/samples/9.x/BuildTime/Program.cs | 40 +++++++++++++++++++ .../samples/9.x/BuildTime/WeatherForecast.cs | 10 +++++ .../BuildTime/appsettings.Development.json | 8 ++++ .../samples/9.x/BuildTime/appsettings.json | 9 +++++ 7 files changed, 96 insertions(+), 3 deletions(-) create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.http create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/WeatherForecast.cs create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/appsettings.Development.json create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/appsettings.json diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 371d0e832f16..7fbe033003a3 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -58,6 +58,8 @@ By default, the generated OpenAPI document is generated in the app's output dire ``` +:::code language="xml" source="~\fundamentals\openapi\samples\9.x\BuildTime\MyTestApi.csproj" highlight="8"::: + The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `./` value in the preceding markup generates the OpenAPI document in the same directory as the project file. ### Modify the output file name @@ -74,17 +76,17 @@ By default, the generated OpenAPI document has the same name as the app's projec Some apps may be configured to generate multiple OpenAPI documents, for example: -* For various versions of an API. +* For different versions of an API. * To distinguish between public and internal APIs. -By default, the build-time document generator generates files for all documents that are configured in an app. To generate for a single document name only, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property: +By default, the build-time document generator creates files for all documents that are configured in an app. To generate for a single document only, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property: ```xml --document-name v2 ``` - +zz ## Customize run-time behavior during build-time document generation The OpenAPI document generation at build-time works by starting the app’s entrypoint with a temporary background server. This is a requirement to produce accurate OpenAPI documents because all information in the OpenAPI document can't be statically analyzed. Because the app's entrypoint is invoked, any logic in the apps' 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 app's entry point is being invoked from build-time document generation. These scenarios include: diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj new file mode 100644 index 000000000000..017842e49dc3 --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -0,0 +1,18 @@ + + + + net9.0 + enable + enable + ./ + + + + + + all + runtime; build; native; contentfiles; analyzers; buildtransitive + + + + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.http b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.http new file mode 100644 index 000000000000..48cebc92d853 --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.http @@ -0,0 +1,6 @@ +@MyTestApi_HostAddress = http://localhost:5276 + +GET {{MyTestApi_HostAddress}}/weatherforecast/ +Accept: application/json + +### diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs new file mode 100644 index 000000000000..eee66cdd2ca7 --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs @@ -0,0 +1,40 @@ +var builder = WebApplication.CreateBuilder(args); + +// Add services to the container. +builder.Services.AddAuthorization(); + +// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi +builder.Services.AddOpenApi(); + +var app = builder.Build(); + +// Configure the HTTP request pipeline. +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} + +app.UseHttpsRedirection(); + +app.UseAuthorization(); + +var summaries = new[] +{ + "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" + }; + +app.MapGet("/weatherforecast", (HttpContext httpContext) => +{ + var forecast = Enumerable.Range(1, 5).Select(index => + new WeatherForecast + { + Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)), + TemperatureC = Random.Shared.Next(-20, 55), + Summary = summaries[Random.Shared.Next(summaries.Length)] + }) + .ToArray(); + return forecast; +}) +.WithName("GetWeatherForecast"); + +app.Run(); diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/WeatherForecast.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/WeatherForecast.cs new file mode 100644 index 000000000000..76e1e3da1158 --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/WeatherForecast.cs @@ -0,0 +1,10 @@ +public class WeatherForecast +{ + public DateOnly Date { get; set; } + + public int TemperatureC { get; set; } + + public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); + + public string? Summary { get; set; } +} diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/appsettings.Development.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/appsettings.Development.json new file mode 100644 index 000000000000..0c208ae9181e --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/appsettings.Development.json @@ -0,0 +1,8 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning" + } + } +} diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/appsettings.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/appsettings.json new file mode 100644 index 000000000000..10f68b8c8b4f --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/appsettings.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning" + } + }, + "AllowedHosts": "*" +} From 446a57968d1f79b2bd2485726d4118a06c34f461 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 12:58:18 -1000 Subject: [PATCH 04/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 13 +++-- .../samples/9.x/BuildTime/MyTestApi.csproj | 27 ++++++++- .../samples/9.x/BuildTime/MyTestApi.json | 56 +++++++++++++++++++ ...stApi.csproj.OpenApiDocumentsDirectory.xml | 18 ++++++ .../samples/9.x/MyOpenApiDocs/MyTestApi.json | 56 +++++++++++++++++++ 5 files changed, 162 insertions(+), 8 deletions(-) create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.OpenApiDocumentsDirectory.xml create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/MyOpenApiDocs/MyTestApi.json diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 7fbe033003a3..6497ae0912c0 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -37,9 +37,10 @@ Run the following command in the directory that contains the project file: ```dotnetcli dotnet add package Microsoft.Extensions.ApiDescription.Server --prerelease ``` + --- -This package automatically generates the Open API document(s) associated with the app during build and populates them into the app's output directory. +The `Microsoft.Extensions.ApiDescription.Server` package automatically generates the Open API document(s) associated with the app during build and populates them into the app's output directory: ```cli $ dotnet build @@ -53,14 +54,14 @@ $ cat bin/Debub/net9.0/{ProjectName}.json By default, the generated OpenAPI document is generated in the app's output directory. To modify the location of the generated file, set the target path in the `OpenApiDocumentsDirectory` property in the project file: ```xml - - ./ - +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj" id="snippet" highlight="8"::: ``` -:::code language="xml" source="~\fundamentals\openapi\samples\9.x\BuildTime\MyTestApi.csproj" highlight="8"::: +The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value in the preceding markup generates the OpenAPI document in the same directory as the project file. To generate the OpenAPI document in a different directory, provide the path relative to the project file. In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling of the project file: -The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `./` value in the preceding markup generates the OpenAPI document in the same directory as the project file. +```xml +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj" id="snippet2" highlight="8"::: +``` ### Modify the output file name diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index 017842e49dc3..f9ec4812a85d 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -1,10 +1,11 @@ - + + net9.0 enable enable - ./ + . @@ -16,3 +17,25 @@ + + + \ No newline at end of file diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json new file mode 100644 index 000000000000..3e53e477e1bc --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json @@ -0,0 +1,56 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "MyTestApi | v1", + "version": "1.0.0" + }, + "paths": { + "/weatherforecast": { + "get": { + "tags": [ + "MyTestApi" + ], + "operationId": "GetWeatherForecast", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "format": "date" + }, + "temperatureC": { + "type": "integer", + "format": "int32" + }, + "temperatureF": { + "type": "integer", + "format": "int32" + }, + "summary": { + "type": "string", + "nullable": true + } + } + } + } + } + } + } + } + } + } + }, + "components": { }, + "tags": [ + { + "name": "MyTestApi" + } + ] +} \ No newline at end of file diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.OpenApiDocumentsDirectory.xml b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.OpenApiDocumentsDirectory.xml new file mode 100644 index 000000000000..20aefaba7e8e --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.OpenApiDocumentsDirectory.xml @@ -0,0 +1,18 @@ + + + + net9.0 + enable + enable + . + + + + + + all + runtime; build; native; contentfiles; analyzers; buildtransitive + + + + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/MyOpenApiDocs/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/MyOpenApiDocs/MyTestApi.json new file mode 100644 index 000000000000..3e53e477e1bc --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/MyOpenApiDocs/MyTestApi.json @@ -0,0 +1,56 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "MyTestApi | v1", + "version": "1.0.0" + }, + "paths": { + "/weatherforecast": { + "get": { + "tags": [ + "MyTestApi" + ], + "operationId": "GetWeatherForecast", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "format": "date" + }, + "temperatureC": { + "type": "integer", + "format": "int32" + }, + "temperatureF": { + "type": "integer", + "format": "int32" + }, + "summary": { + "type": "string", + "nullable": true + } + } + } + } + } + } + } + } + } + } + }, + "components": { }, + "tags": [ + { + "name": "MyTestApi" + } + ] +} \ No newline at end of file From f6ea15c0a12ae1d8fccab77f7f8bbb162e3f9c14 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 14:45:48 -1000 Subject: [PATCH 05/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 9 ++++- .../samples/9.x/BuildTime/MyTestApi.csproj | 37 +++++++++++++------ 2 files changed, 33 insertions(+), 13 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 6497ae0912c0..b5c906f005d2 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -53,14 +53,19 @@ $ cat bin/Debub/net9.0/{ProjectName}.json By default, the generated OpenAPI document is generated in the app's output directory. To modify the location of the generated file, set the target path in the `OpenApiDocumentsDirectory` property in the project file: + + ```xml :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj" id="snippet" highlight="8"::: ``` -The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value in the preceding markup generates the OpenAPI document in the same directory as the project file. To generate the OpenAPI document in a different directory, provide the path relative to the project file. In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling of the project file: +The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value in the preceding markup generates the OpenAPI document in the same directory as the project file. To generate the OpenAPI document in a different directory, provide the path relative to the project file. In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory of the project directory: ```xml -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj" id="snippet2" highlight="8"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj" id="snippet2" highlight="28"::: ``` ### Modify the output file name diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index f9ec4812a85d..c00c75d49a69 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -1,4 +1,4 @@ - + @@ -9,33 +9,48 @@ - - + + all runtime; build; native; contentfiles; analyzers; buildtransitive - - \ No newline at end of file + + --> + + + From d1f346db03a3cc4687f5f12bb1c19a4f52f82101 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 14:46:45 -1000 Subject: [PATCH 06/71] Fix and Edit build time OpenAPI/ra --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index b5c906f005d2..989fa73211a7 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -58,15 +58,14 @@ By default, the generated OpenAPI document is generated in the app's output dire Which generates misleading error: Missing required option '--project'. --> -```xml :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj" id="snippet" highlight="8"::: -``` + The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value in the preceding markup generates the OpenAPI document in the same directory as the project file. To generate the OpenAPI document in a different directory, provide the path relative to the project file. In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory of the project directory: -```xml + :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj" id="snippet2" highlight="28"::: -``` + ### Modify the output file name From acd7cb8573f215bbbb76c4b84d649add9ac2255d Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 15:59:54 -1000 Subject: [PATCH 07/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 13 +---- .../samples/9.x/BuildTime/MyTestApi.csproj | 46 ++------------- .../samples/9.x/BuildTime/MyTestApi.json | 56 ------------------- ...stApi.csproj.OpenApiDocumentsDirectory.xml | 18 ------ .../9.x/BuildTime/csproj/MyTestApi.csproj.xml | 36 ++++++++++++ 5 files changed, 44 insertions(+), 125 deletions(-) delete mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json delete mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.OpenApiDocumentsDirectory.xml create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 989fa73211a7..100994430bac 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -58,24 +58,17 @@ By default, the generated OpenAPI document is generated in the app's output dire Which generates misleading error: Missing required option '--project'. --> -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj" id="snippet" highlight="8"::: - +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet_1" highlight="9"::: The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value in the preceding markup generates the OpenAPI document in the same directory as the project file. To generate the OpenAPI document in a different directory, provide the path relative to the project file. In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory of the project directory: - -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj" id="snippet2" highlight="28"::: - +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet2" highlight="5"::: ### Modify the output file name By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the generated file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property: -```xml - - --file-name my-open-api - -``` +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet_file_name" highlight="5-6"::: ### Select the OpenAPI document to generate diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index c00c75d49a69..dc63735f7a1f 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -1,56 +1,20 @@ - - + net9.0 enable enable - . + --file-name my-open-api + - - - all - runtime; build; native; contentfiles; analyzers; buildtransitive - - - - - - - - - diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json deleted file mode 100644 index 3e53e477e1bc..000000000000 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json +++ /dev/null @@ -1,56 +0,0 @@ -{ - "openapi": "3.0.1", - "info": { - "title": "MyTestApi | v1", - "version": "1.0.0" - }, - "paths": { - "/weatherforecast": { - "get": { - "tags": [ - "MyTestApi" - ], - "operationId": "GetWeatherForecast", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "format": "date" - }, - "temperatureC": { - "type": "integer", - "format": "int32" - }, - "temperatureF": { - "type": "integer", - "format": "int32" - }, - "summary": { - "type": "string", - "nullable": true - } - } - } - } - } - } - } - } - } - } - }, - "components": { }, - "tags": [ - { - "name": "MyTestApi" - } - ] -} \ No newline at end of file diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.OpenApiDocumentsDirectory.xml b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.OpenApiDocumentsDirectory.xml deleted file mode 100644 index 20aefaba7e8e..000000000000 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.OpenApiDocumentsDirectory.xml +++ /dev/null @@ -1,18 +0,0 @@ - - - - net9.0 - enable - enable - . - - - - - - all - runtime; build; native; contentfiles; analyzers; buildtransitive - - - - diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml new file mode 100644 index 000000000000..21b5336a29d9 --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml @@ -0,0 +1,36 @@ + + + + net9.0 + enable + enable + --file-name my-open-api + + + + + + + + + + net9.0xcf klws, + enable + enable + . + + + + + + + + net9.0 + enable + enable + ../MyOpenApiDocs + + + From a9dcecf58a0aa18dabda552c6113d6ba6af293bc Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 16:12:46 -1000 Subject: [PATCH 08/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 14 +++---- .../samples/9.x/BuildTime/MyTestApi.csproj | 8 +++- .../9.x/BuildTime/csproj/MyTestApi.csproj.txt | 39 +++++++++++++++++++ .../9.x/BuildTime/csproj/MyTestApi.csproj.xml | 36 ----------------- 4 files changed, 50 insertions(+), 47 deletions(-) create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt delete mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 100994430bac..7c251d3c323b 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -58,17 +58,17 @@ By default, the generated OpenAPI document is generated in the app's output dire Which generates misleading error: Missing required option '--project'. --> -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet_1" highlight="9"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt" id="snippet_1"::: The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value in the preceding markup generates the OpenAPI document in the same directory as the project file. To generate the OpenAPI document in a different directory, provide the path relative to the project file. In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory of the project directory: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet2" highlight="5"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt" id="snippet2"::: ### Modify the output file name By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the generated file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet_file_name" highlight="5-6"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt" id="snippet_file_name" ::: ### Select the OpenAPI document to generate @@ -79,12 +79,8 @@ Some apps may be configured to generate multiple OpenAPI documents, for example: By default, the build-time document generator creates files for all documents that are configured in an app. To generate for a single document only, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property: -```xml - - --document-name v2 - -``` -zz +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt" id="snippet_doc_name"::: + ## Customize run-time behavior during build-time document generation The OpenAPI document generation at build-time works by starting the app’s entrypoint with a temporary background server. This is a requirement to produce accurate OpenAPI documents because all information in the OpenAPI document can't be statically analyzed. Because the app's entrypoint is invoked, any logic in the apps' 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 app's entry point is being invoked from build-time document generation. These scenarios include: diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index dc63735f7a1f..805e8a9a30ef 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -4,10 +4,14 @@ net9.0 enable enable - --file-name my-open-api - + + + --document-name v2 + + + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt new file mode 100644 index 000000000000..a6d7a0090466 --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt @@ -0,0 +1,39 @@ + + + + --file-name my-open-api + + + + + . + + + + + + ../MyOpenApiDocs + + + + + + --document-name v2 + + + + + + + + + + + + + + + + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml deleted file mode 100644 index 21b5336a29d9..000000000000 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml +++ /dev/null @@ -1,36 +0,0 @@ - - - - net9.0 - enable - enable - --file-name my-open-api - - - - - - - - - - net9.0xcf klws, - enable - enable - . - - - - - - - - net9.0 - enable - enable - ../MyOpenApiDocs - - - From b074ef60425c539ffcee3c2ed7c78cd38ae9bd41 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 16:57:10 -1000 Subject: [PATCH 09/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 27 ++++++++- .../samples/9.x/BuildTime/MyTestApi.csproj | 4 +- .../9.x/BuildTime/csproj/MyTestApi.json | 56 +++++++++++++++++++ 3 files changed, 83 insertions(+), 4 deletions(-) create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 7c251d3c323b..f02ffdb18fd1 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -42,11 +42,36 @@ dotnet add package Microsoft.Extensions.ApiDescription.Server --prerelease The `Microsoft.Extensions.ApiDescription.Server` package automatically generates the Open API document(s) associated with the app during build and populates them into the app's output directory: +Consider a template created API app named `MyTestApi`: + +### [Visual Studio](#tab/visual-studio) + +The output tab of Visual Studio includes the output similar to the following: + +```text +1>Generating document named 'v1'. +1>Writing document named 'v1' to 'MyProjectPath\obj\MyTestApi.json'. +``` + +### [.NET CLI](#tab/net-cli) + ```cli $ dotnet build -$ cat bin/Debub/net9.0/{ProjectName}.json +$ cat obj/MyTestApi.json ``` +--- + +The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, title, endpoints, and more](https://learn.openapis.org/specification/structure.html). The following JSON shows the first few lines of obj/MyTestApi.json file: + +```json +{ + "openapi": "3.0.0", + "info": { + "title": "MyTestApi", + + + ## Customize build-time document generation ### Modify the output directory of the generated Open API file diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index 805e8a9a30ef..5da2f54555b3 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -7,9 +7,7 @@ - - --document-name v2 - + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json new file mode 100644 index 000000000000..3e53e477e1bc --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json @@ -0,0 +1,56 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "MyTestApi | v1", + "version": "1.0.0" + }, + "paths": { + "/weatherforecast": { + "get": { + "tags": [ + "MyTestApi" + ], + "operationId": "GetWeatherForecast", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "format": "date" + }, + "temperatureC": { + "type": "integer", + "format": "int32" + }, + "temperatureF": { + "type": "integer", + "format": "int32" + }, + "summary": { + "type": "string", + "nullable": true + } + } + } + } + } + } + } + } + } + } + }, + "components": { }, + "tags": [ + { + "name": "MyTestApi" + } + ] +} \ No newline at end of file From 450f254a5a247817a62d8e92a91f819085084c5a Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 17:00:42 -1000 Subject: [PATCH 10/71] Fix and Edit build time OpenAPI/ra --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 8 +------- .../openapi/samples/9.x/BuildTime/csproj/MyTestApi.json | 7 +++++-- 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index f02ffdb18fd1..8af2f07a6ae9 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -64,13 +64,7 @@ $ cat obj/MyTestApi.json The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, title, endpoints, and more](https://learn.openapis.org/specification/structure.html). The following JSON shows the first few lines of obj/MyTestApi.json file: -```json -{ - "openapi": "3.0.0", - "info": { - "title": "MyTestApi", - - +:::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" id="snippet_1"::: ## Customize build-time document generation diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json index 3e53e477e1bc..e1caf4890b1e 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json @@ -1,3 +1,5 @@ +//Copy from \obj\MyTestApi.json +// { "openapi": "3.0.1", "info": { @@ -14,6 +16,7 @@ "responses": { "200": { "description": "OK", + // "content": { "application/json": { "schema": { @@ -47,10 +50,10 @@ } } }, - "components": { }, + "components": {}, "tags": [ { "name": "MyTestApi" } ] -} \ No newline at end of file +} From ce6735fdcd3a79ef704681d2a2d0546021c72537 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 17:12:26 -1000 Subject: [PATCH 11/71] Fix and Edit build time OpenAPI/ra --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 8 ++++---- .../csproj/{MyTestApi.csproj.txt => MyTestApi.csproj.xml} | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) rename aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/{MyTestApi.csproj.txt => MyTestApi.csproj.xml} (78%) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 8af2f07a6ae9..62e484a00e1b 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -77,17 +77,17 @@ By default, the generated OpenAPI document is generated in the app's output dire Which generates misleading error: Missing required option '--project'. --> -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt" id="snippet_1"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet_1"::: The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value in the preceding markup generates the OpenAPI document in the same directory as the project file. To generate the OpenAPI document in a different directory, provide the path relative to the project file. In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory of the project directory: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt" id="snippet2"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet2"::: ### Modify the output file name By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the generated file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt" id="snippet_file_name" ::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet_file_name" ::: ### Select the OpenAPI document to generate @@ -98,7 +98,7 @@ Some apps may be configured to generate multiple OpenAPI documents, for example: By default, the build-time document generator creates files for all documents that are configured in an app. To generate for a single document only, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt" id="snippet_doc_name"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet_doc_name"::: ## Customize run-time behavior during build-time document generation diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml similarity index 78% rename from aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt rename to aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml index a6d7a0090466..ea009eb31b43 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.txt +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml @@ -1,7 +1,7 @@ - - + + --file-name my-open-api From 82d8440fb30f109ad5fb80965394104730e1c03c Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 18:15:18 -1000 Subject: [PATCH 12/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 40 ++++++++++++++----- .../samples/9.x/BuildTime/MyTestApi.csproj | 4 +- .../openapi/samples/9.x/BuildTime/Program.cs | 10 ++++- ...stApi.csproj.xml => MyTestApi.csproj.html} | 16 +------- 4 files changed, 42 insertions(+), 28 deletions(-) rename aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/{MyTestApi.csproj.xml => MyTestApi.csproj.html} (73%) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 62e484a00e1b..a21d83e07276 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -55,6 +55,8 @@ The output tab of Visual Studio includes the output similar to the following: ### [.NET CLI](#tab/net-cli) +The following commands build the app and display the generated OpenAPI document: + ```cli $ dotnet build $ cat obj/MyTestApi.json @@ -62,9 +64,9 @@ $ cat obj/MyTestApi.json --- -The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, title, endpoints, and more](https://learn.openapis.org/specification/structure.html). The following JSON shows the first few lines of obj/MyTestApi.json file: +The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, title, endpoints, and more](https://learn.openapis.org/specification/structure.html). The first few lines of obj/MyTestApi.json file: -:::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" id="snippet_1"::: +:::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" id="snippet_1" highlight="4-5"::: ## Customize build-time document generation @@ -77,17 +79,19 @@ By default, the generated OpenAPI document is generated in the app's output dire Which generates misleading error: Missing required option '--project'. --> -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet_1"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_1" highlight="2"::: The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value in the preceding markup generates the OpenAPI document in the same directory as the project file. To generate the OpenAPI document in a different directory, provide the path relative to the project file. In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory of the project directory: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet2"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet2" highlight="2"::: ### Modify the output file name By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the generated file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet_file_name" ::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_file_name" highlight="2"::: + +In development mode, the preceding markup generates the `obj/my-open-api.json` file. ### Select the OpenAPI document to generate @@ -98,16 +102,25 @@ Some apps may be configured to generate multiple OpenAPI documents, for example: By default, the build-time document generator creates files for all documents that are configured in an app. To generate for a single document only, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml" id="snippet_doc_name"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_doc_name"::: + + ## Customize run-time behavior during build-time document generation -The OpenAPI document generation at build-time works by starting the app’s entrypoint with a temporary background server. This is a requirement to produce accurate OpenAPI documents because all information in the OpenAPI document can't be statically analyzed. Because the app's entrypoint is invoked, any logic in the apps' 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 app's entry point is being invoked from build-time document generation. These scenarios include: +The OpenAPI document generation at build-time works by starting the app’s entrypoint with a temporary background server. This is a requirement to produce accurate OpenAPI documents because all information in the OpenAPI document can't be statically analyzed. Because the app's entrypoint is invoked, any logic in the apps' startup is invoked. The app's entrypoint includes code that injects services into the DI container or reads from configuration. In some scenarios, it's necessary to restrict the code paths that run when the app's entry point is being invoked from build-time document generation. These scenarios include: -- Not reading from certain configuration strings -- Not registering database-related services +- Not reading from certain configuration strings. +- Not registering database-related services. -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: +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: ```csharp using System.Reflection; @@ -116,6 +129,11 @@ var builder = WebApplication.CreateBuilder(); if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") { - builders.Services.AddDefaults(); + builder.Services.AddDefaults(); } ``` + + \ No newline at end of file diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index 5da2f54555b3..3c5528153bcc 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -7,7 +7,9 @@ - + + --file-name my-open-api + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs index eee66cdd2ca7..edbb686ff85d 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs @@ -1,6 +1,12 @@ -var builder = WebApplication.CreateBuilder(args); +using System.Reflection; + +var builder = WebApplication.CreateBuilder(); + +if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") +{ + builder.Services.AddDefaults(); +} -// Add services to the container. builder.Services.AddAuthorization(); // Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html similarity index 73% rename from aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml rename to aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html index ea009eb31b43..28f42d911c92 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.xml +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html @@ -1,5 +1,5 @@ @@ -8,6 +8,7 @@ + . @@ -24,16 +25,3 @@ - - - - - - - - - - - - - From 29b0b1925819b09dc2ec1663224d8e28e18f05ea Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 18:16:06 -1000 Subject: [PATCH 13/71] Fix and Edit build time OpenAPI/ra --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 5 ----- .../fundamentals/openapi/samples/9.x/BuildTime/Program.cs | 2 +- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index a21d83e07276..807457b0fbf5 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -132,8 +132,3 @@ if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") builder.Services.AddDefaults(); } ``` - - \ No newline at end of file diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs index edbb686ff85d..2316b7419088 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs @@ -4,7 +4,7 @@ if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") { - builder.Services.AddDefaults(); + // builder.Services.AddDefaults(); } builder.Services.AddAuthorization(); From 30cb83d9fa669e9cdb0bb4cdec163945651b8157 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 18:22:23 -1000 Subject: [PATCH 14/71] Fix and Edit build time OpenAPI/ra --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 807457b0fbf5..7123ceaa4f69 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -46,7 +46,7 @@ Consider a template created API app named `MyTestApi`: ### [Visual Studio](#tab/visual-studio) -The output tab of Visual Studio includes the output similar to the following: +The Output tab in Visual Studio includes information similar to the following: ```text 1>Generating document named 'v1'. @@ -74,11 +74,6 @@ The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, tit By default, the generated OpenAPI document is generated in the app's output directory. To modify the location of the generated file, set the target path in the `OpenApiDocumentsDirectory` property in the project file: - - :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_1" highlight="2"::: The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value in the preceding markup generates the OpenAPI document in the same directory as the project file. To generate the OpenAPI document in a different directory, provide the path relative to the project file. In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory of the project directory: From aa7a99308f20c148231cd5dfaae1efb13bb319db Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 18:36:55 -1000 Subject: [PATCH 15/71] Fix and Edit build time OpenAPI/ra --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 8 ++++++-- .../openapi/samples/9.x/BuildTime/MyTestApi.csproj | 8 +------- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 7123ceaa4f69..0f02d39aed7d 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -40,7 +40,7 @@ dotnet add package Microsoft.Extensions.ApiDescription.Server --prerelease --- -The `Microsoft.Extensions.ApiDescription.Server` package automatically generates the Open API document(s) associated with the app during build and populates them into the app's output directory: +The `Microsoft.Extensions.ApiDescription.Server` package automatically generates the Open API document(s) associated with the app during build and places them in the app's `obj` directory: Consider a template created API app named `MyTestApi`: @@ -86,7 +86,7 @@ By default, the generated OpenAPI document has the same name as the app's projec :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_file_name" highlight="2"::: -In development mode, the preceding markup generates the `obj/my-open-api.json` file. +The preceding markup generates the `obj/my-open-api.json` file. ### Select the OpenAPI document to generate @@ -127,3 +127,7 @@ if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") builder.Services.AddDefaults(); } ``` + +## OpenAPI document cleanup + +Then generated OpenAPI documents are not cleaned up by `dotnet clean` or **Build > Clean Solution** in Visual Studio. To clean up the generated OpenAPI documents, delete the `obj` directory or the directory where the OpenAPI documents are generated. diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index 3c5528153bcc..5722b7cbb872 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -5,13 +5,7 @@ enable enable - - - - --file-name my-open-api - - - + From 691ddd0f8fd0d5bfb3b485084d97b579bbf03f33 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Wed, 14 Aug 2024 18:42:16 -1000 Subject: [PATCH 16/71] Fix and Edit build time OpenAPI/ra --- .../BuildTime/csproj/MyTestApi.csproj.html | 35 ++++++++++--------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html index 28f42d911c92..f8355ade546b 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html @@ -1,27 +1,28 @@ - - + --file-name my-open-api - - - - + + + . - - - - - + + + + ../MyOpenApiDocs - - - + + - --document-name v2 + --document-name v2 - From 967964bcdb7c12f5c5d7a830a835ddf2b3b5b486 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 09:08:32 -1000 Subject: [PATCH 17/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 15 ++++++++++++--- .../samples/9.x/BuildTime/MyTestApi.csproj | 2 +- .../9.x/BuildTime/csproj/MyTestApi.csproj.html | 11 +++++++++++ 3 files changed, 24 insertions(+), 4 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 0f02d39aed7d..d04b2e6ee958 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -64,19 +64,28 @@ $ cat obj/MyTestApi.json --- -The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, title, endpoints, and more](https://learn.openapis.org/specification/structure.html). The first few lines of obj/MyTestApi.json file: +The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, title, endpoints, and more](https://learn.openapis.org/specification/structure.html). The first few lines of `obj/MyTestApi.json` file: :::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" id="snippet_1" highlight="4-5"::: ## Customize build-time document generation +Build-time document generation can be customized with properties added to the project file. [dotnet](/dotnet/core/tools/) parses the `ApiDescription.Server` properties in the project file and provides them to the build-time document generator. The following properties are available and explained in the following sections: + +:::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" id="snippet_all"::: + ### Modify the output directory of the generated Open API file -By default, the generated OpenAPI document is generated in the app's output directory. To modify the location of the generated file, set the target path in the `OpenApiDocumentsDirectory` property in the project file: +By default, the generated OpenAPI document is generated in the `obj` directory. The value of the `OpenApiDocumentsDirectory` property: + +* Sets the location of the generated file. +* Is resolved relative to the project file. + +The following example generates the OpenAPI document in the same directory as the project file: :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_1" highlight="2"::: -The value of `OpenApiDocumentsDirectory` is resolved relative to the project file. Using the `.` value in the preceding markup generates the OpenAPI document in the same directory as the project file. To generate the OpenAPI document in a different directory, provide the path relative to the project file. In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory of the project directory: +In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory of the project directory: :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet2" highlight="2"::: diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index 5722b7cbb872..f4e606b21426 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -5,7 +5,7 @@ enable enable - + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html index f8355ade546b..8220518b49a7 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html @@ -6,11 +6,13 @@ That's why this is stored as an HTML file. --> + --file-name my-open-api + . @@ -21,8 +23,17 @@ ../MyOpenApiDocs + --document-name v2 + + + + . + --file-name my-open-api + --document-name v2 + + From 72077871d6d5a423c7d931db842533f21b9dd7b3 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 09:17:50 -1000 Subject: [PATCH 18/71] Fix and Edit build time OpenAPI/ra --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index d04b2e6ee958..c144c4abdafc 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -72,7 +72,7 @@ The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, tit Build-time document generation can be customized with properties added to the project file. [dotnet](/dotnet/core/tools/) parses the `ApiDescription.Server` properties in the project file and provides them to the build-time document generator. The following properties are available and explained in the following sections: -:::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" id="snippet_all"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_all" highlight="2-4"::: ### Modify the output directory of the generated Open API file From 830bd950d60aec75b74579090e88caf811b758ea Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 09:26:24 -1000 Subject: [PATCH 19/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index c144c4abdafc..839f25610d74 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -16,9 +16,9 @@ In a typical web apps, OpenAPI documents are generated at run-time and served vi Generating OpenAPI documentation during the app's build step can be useful for documentation that is: -- Committed into source control -- Used for spec-based integration testing -- Served statically from the web server +- Committed into source control. +- Used for spec-based integration testing. +- Served statically from the web server. To add support for generating OpenAPI documents at build time, install the [`Microsoft.Extensions.ApiDescription.Server`](https://www.nuget.org/packages/Microsoft.Extensions.ApiDescription.Server) NuGet package: @@ -46,7 +46,7 @@ Consider a template created API app named `MyTestApi`: ### [Visual Studio](#tab/visual-studio) -The Output tab in Visual Studio includes information similar to the following: +The Output tab in Visual Studio when building the app includes information similar to the following: ```text 1>Generating document named 'v1'. @@ -70,7 +70,7 @@ The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, tit ## Customize build-time document generation -Build-time document generation can be customized with properties added to the project file. [dotnet](/dotnet/core/tools/) parses the `ApiDescription.Server` properties in the project file and provides them to the build-time document generator. The following properties are available and explained in the following sections: +Build-time document generation can be customized with properties added to the project file. [dotnet](/dotnet/core/tools/) parses the `ApiDescription.Server` properties in the project file and provides the property and values as arguments to the build-time document generator. The following properties are available and explained in the following sections: :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_all" highlight="2-4"::: @@ -85,13 +85,13 @@ The following example generates the OpenAPI document in the same directory as th :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_1" highlight="2"::: -In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory of the project directory: +In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory to the project directory: :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet2" highlight="2"::: ### Modify the output file name -By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the generated file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property: +By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the generated file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property:zz :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_file_name" highlight="2"::: From bf297698c5aba98130fe1fb2d71b6268b79499da Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 10:26:51 -1000 Subject: [PATCH 20/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 839f25610d74..7309c0b40044 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -91,11 +91,11 @@ In the following example, the OpenAPI document is generated in the `MyOpenApiDoc ### Modify the output file name -By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the generated file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property:zz +By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the generated file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property: :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_file_name" highlight="2"::: -The preceding markup generates the `obj/my-open-api.json` file. +The preceding markup configures creation of the `obj/my-open-api.json` file. ### Select the OpenAPI document to generate @@ -119,12 +119,14 @@ What's the equivalent of ## Customize run-time behavior during build-time document generation -The OpenAPI document generation at build-time works by starting the app’s entrypoint with a temporary background server. This is a requirement to produce accurate OpenAPI documents because all information in the OpenAPI document can't be statically analyzed. Because the app's entrypoint is invoked, any logic in the apps' startup is invoked. The app's entrypoint includes code that injects services into the DI container or reads from configuration. In some scenarios, it's necessary to restrict the code paths that run when the app's entry point is being invoked from build-time document generation. These scenarios include: +OpenAPI document generation at build-time works by starting the app’s entry point with a temporary background server. This approach is necessary to produce accurate OpenAPI documents, as not all information can be statically analyzed. When the app’s entry point is invoked, any logic in the app’s startup is executed, including code that injects services into the DI container or reads from configuration. -- Not reading from certain configuration strings. +In some scenarios, it's important to restrict certain code paths when the app's entry point is invoked during build-time document generation. These scenarios include: + +- Not reading from specific configuration strings. - Not registering database-related services. -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: +To prevent these code paths from being invoked by the build-time generation pipeline, they can be conditioned behind a check of the entry assembly: ```csharp using System.Reflection; @@ -139,4 +141,4 @@ if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") ## OpenAPI document cleanup -Then generated OpenAPI documents are not cleaned up by `dotnet clean` or **Build > Clean Solution** in Visual Studio. To clean up the generated OpenAPI documents, delete the `obj` directory or the directory where the OpenAPI documents are generated. +Then generated OpenAPI documents are not cleaned up by `dotnet clean` or **Build > Clean Solution** in Visual Studio. To remove the generated OpenAPI documents, delete the `obj` directory or the directory specified by the `OpenApiDocumentsDirectory` property. \ No newline at end of file From f8c51cb3212ecf2613235ac286c5bd2b82199e57 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 13:47:23 -1000 Subject: [PATCH 21/71] Fix and Edit build time OpenAPI/ra --- .../fundamentals/openapi/buildtime-openapi.md | 2 + .../samples/9.x/BuildTime/MyTestApi.csproj | 4 ++ .../9.x/BuildTime/{csproj => }/MyTestApi.json | 13 ++--- .../9.x/BuildTime/csproj/MyTestApi.csproj.php | 39 +++++++++++++ .../openapi/samples/9.x/BuildTime/movie.cs | 11 ++++ .../openapi/samples/9.x/MyTestApi.json | 56 +++++++++++++++++++ 6 files changed, 117 insertions(+), 8 deletions(-) rename aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/{csproj => }/MyTestApi.json (87%) create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/movie.cs create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/MyTestApi.json diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 7309c0b40044..224cbfc27103 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -74,6 +74,8 @@ Build-time document generation can be customized with properties added to the pr :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_all" highlight="2-4"::: +:::code language="php" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet_all" highlight="2-4"::: + ### Modify the output directory of the generated Open API file By default, the generated OpenAPI document is generated in the `obj` directory. The value of the `OpenApiDocumentsDirectory` property: diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index f4e606b21426..ee11e0b59778 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -6,6 +6,10 @@ enable + + ./ + + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json similarity index 87% rename from aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json rename to aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json index e1caf4890b1e..517a01a227e7 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json @@ -1,22 +1,19 @@ -//Copy from \obj\MyTestApi.json -// { "openapi": "3.0.1", "info": { - "title": "MyTestApi | v1", + "title": "GetDocument.Insider | v1", "version": "1.0.0" }, "paths": { "/weatherforecast": { "get": { "tags": [ - "MyTestApi" + "GetDocument.Insider" ], "operationId": "GetWeatherForecast", "responses": { "200": { "description": "OK", - // "content": { "application/json": { "schema": { @@ -50,10 +47,10 @@ } } }, - "components": {}, + "components": { }, "tags": [ { - "name": "MyTestApi" + "name": "GetDocument.Insider" } ] -} +} \ No newline at end of file diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php new file mode 100644 index 000000000000..8220518b49a7 --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php @@ -0,0 +1,39 @@ + + + + + --file-name my-open-api + + + + + + . + + + + + ../MyOpenApiDocs + + + + + + --document-name v2 + + + + + + . + --file-name my-open-api + --document-name v2 + + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/movie.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/movie.cs new file mode 100644 index 000000000000..6ef53b99947e --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/movie.cs @@ -0,0 +1,11 @@ +using System.ComponentModel.DataAnnotations; + +public class Movie +{ + public int Id { get; set; } + public string? Title { get; set; } + [DataType(DataType.Date)] + public DateTime ReleaseDate { get; set; } + public string? Genre { get; set; } + public decimal Price { get; set; } +} diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/MyTestApi.json new file mode 100644 index 000000000000..517a01a227e7 --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/MyTestApi.json @@ -0,0 +1,56 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "GetDocument.Insider | v1", + "version": "1.0.0" + }, + "paths": { + "/weatherforecast": { + "get": { + "tags": [ + "GetDocument.Insider" + ], + "operationId": "GetWeatherForecast", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "format": "date" + }, + "temperatureC": { + "type": "integer", + "format": "int32" + }, + "temperatureF": { + "type": "integer", + "format": "int32" + }, + "summary": { + "type": "string", + "nullable": true + } + } + } + } + } + } + } + } + } + } + }, + "components": { }, + "tags": [ + { + "name": "GetDocument.Insider" + } + ] +} \ No newline at end of file From 03444b0a1bae7cb8d5d27c56020c8edd252e851c Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 13:51:44 -1000 Subject: [PATCH 22/71] Fix and Edit build time OpenAPI/ra --- .../openapi/samples/9.x/BuildTime/MyTestApi.csproj | 6 +++--- .../{MyTestApi.csproj.html => MyTestApi.csproj.html.txt} | 0 2 files changed, 3 insertions(+), 3 deletions(-) rename aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/{MyTestApi.csproj.html => MyTestApi.csproj.html.txt} (100%) diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index ee11e0b59778..d64b34531f20 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -6,9 +6,9 @@ enable - - ./ - + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html.txt similarity index 100% rename from aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html rename to aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html.txt From bc64f738e8553aab0ed060e34bb7a645cd7498a1 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 13:52:35 -1000 Subject: [PATCH 23/71] Fix and Edit build time OpenAPI/ra --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 224cbfc27103..8e90c0807b41 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -72,8 +72,6 @@ The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, tit Build-time document generation can be customized with properties added to the project file. [dotnet](/dotnet/core/tools/) parses the `ApiDescription.Server` properties in the project file and provides the property and values as arguments to the build-time document generator. The following properties are available and explained in the following sections: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_all" highlight="2-4"::: - :::code language="php" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet_all" highlight="2-4"::: ### Modify the output directory of the generated Open API file @@ -85,17 +83,17 @@ By default, the generated OpenAPI document is generated in the `obj` directory. The following example generates the OpenAPI document in the same directory as the project file: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_1" highlight="2"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet_1" highlight="2"::: In the following example, the OpenAPI document is generated in the `MyOpenApiDocs` directory, which is a sibling directory to the project directory: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet2" highlight="2"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet2" highlight="2"::: ### Modify the output file name By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the generated file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_file_name" highlight="2"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet_file_name" highlight="2"::: The preceding markup configures creation of the `obj/my-open-api.json` file. @@ -108,7 +106,7 @@ Some apps may be configured to generate multiple OpenAPI documents, for example: By default, the build-time document generator creates files for all documents that are configured in an app. To generate for a single document only, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property: -:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html" id="snippet_doc_name"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet_doc_name"::: +using ControllerApi.Data; +using Microsoft.EntityFrameworkCore; +using System.Reflection; + +var builder = WebApplication.CreateBuilder(args); + +if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") +{ + builder.Services.AddDbContext(options => + options.UseSqlServer(builder.Configuration.GetConnectionString("ControllerApiContext") + ?? throw new InvalidOperationException("Connection string 'ControllerApiContext' not found."))); +} + +builder.Services.AddControllers(); +builder.Services.AddOpenApi(); + +var app = builder.Build(); + +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} + +app.UseHttpsRedirection(); + +app.UseAuthorization(); + +app.MapControllers(); + +app.Run(); + +#endif \ No newline at end of file From f54bd9de897acd00551cd4e6b59ce2d0acc106eb Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 14:35:30 -1000 Subject: [PATCH 25/71] Add SqlDB to skip --- .../fundamentals/openapi/samples/9.x/BuildTime/Skip.cs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs index f1735387a2d5..db7f6af5a487 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs @@ -6,12 +6,12 @@ var builder = WebApplication.CreateBuilder(args); -if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") -{ +//if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") +//{ builder.Services.AddDbContext(options => options.UseSqlServer(builder.Configuration.GetConnectionString("ControllerApiContext") ?? throw new InvalidOperationException("Connection string 'ControllerApiContext' not found."))); -} +//} builder.Services.AddControllers(); builder.Services.AddOpenApi(); @@ -31,4 +31,4 @@ app.Run(); -#endif \ No newline at end of file +#endif From 1b04232d9589734f999611eb465f7e7932af63ff Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 14:44:45 -1000 Subject: [PATCH 26/71] Add SqlDB to skip --- .../fundamentals/openapi/buildtime-openapi.md | 18 +++++------------- .../openapi/samples/9.x/BuildTime/Skip.cs | 6 +++--- 2 files changed, 8 insertions(+), 16 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 8e90c0807b41..2979893283d2 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -50,7 +50,7 @@ The Output tab in Visual Studio when building the app includes information simil ```text 1>Generating document named 'v1'. -1>Writing document named 'v1' to 'MyProjectPath\obj\MyTestApi.json'. +1>Writing document named 'v1' to 'MyProjectPath/obj/MyTestApi.json'. ``` ### [.NET CLI](#tab/net-cli) @@ -72,7 +72,7 @@ The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, tit Build-time document generation can be customized with properties added to the project file. [dotnet](/dotnet/core/tools/) parses the `ApiDescription.Server` properties in the project file and provides the property and values as arguments to the build-time document generator. The following properties are available and explained in the following sections: -:::code language="php" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet_all" highlight="2-4"::: +:::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet_all" highlight="2-4"::: ### Modify the output directory of the generated Open API file @@ -128,17 +128,9 @@ In some scenarios, it's important to restrict certain code paths when the app's To prevent these code paths from being invoked by the build-time generation pipeline, they can be conditioned behind a check of the entry assembly: -```csharp -using System.Reflection; - -var builder = WebApplication.CreateBuilder(); - -if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") -{ - builder.Services.AddDefaults(); -} -``` +:::code language="csharp" source="~/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs +" id="snippet_1" highlight="7-12"::: ## OpenAPI document cleanup -Then generated OpenAPI documents are not cleaned up by `dotnet clean` or **Build > Clean Solution** in Visual Studio. To remove the generated OpenAPI documents, delete the `obj` directory or the directory specified by the `OpenApiDocumentsDirectory` property. \ No newline at end of file +Then generated OpenAPI documents are not cleaned up by `dotnet clean` or **Build > Clean Solution** in Visual Studio. To remove the generated OpenAPI documents, delete the `obj` directory or the directory specified by the `OpenApiDocumentsDirectory` property. diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs index db7f6af5a487..2800e873ab9c 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs @@ -6,12 +6,12 @@ var builder = WebApplication.CreateBuilder(args); -//if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") -//{ +if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") +{ builder.Services.AddDbContext(options => options.UseSqlServer(builder.Configuration.GetConnectionString("ControllerApiContext") ?? throw new InvalidOperationException("Connection string 'ControllerApiContext' not found."))); -//} +} builder.Services.AddControllers(); builder.Services.AddOpenApi(); From b21f9f565de515f16ccfc72730880509bd617dee Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 15:38:30 -1000 Subject: [PATCH 27/71] Add SqlDB to skip --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 6 +++--- .../fundamentals/openapi/samples/9.x/BuildTime/Program.cs | 5 ----- .../fundamentals/openapi/samples/9.x/BuildTime/Skip.cs | 4 ++-- .../samples/9.x/BuildTime/{ => csproj}/MyTestApi.json | 0 4 files changed, 5 insertions(+), 10 deletions(-) rename aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/{ => csproj}/MyTestApi.json (100%) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 2979893283d2..d4ec4e55b966 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -66,6 +66,7 @@ $ cat obj/MyTestApi.json The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, title, endpoints, and more](https://learn.openapis.org/specification/structure.html). The first few lines of `obj/MyTestApi.json` file: + :::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" id="snippet_1" highlight="4-5"::: ## Customize build-time document generation @@ -109,7 +110,7 @@ By default, the build-time document generator creates files for all documents th :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet_doc_name"::: +// using ControllerApi.Data; using Microsoft.EntityFrameworkCore; using System.Reflection; @@ -30,5 +30,5 @@ app.MapControllers(); app.Run(); - +// #endif diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json similarity index 100% rename from aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json rename to aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json From 81fc99ade21738ef82fce6e128b4bfc6461712c2 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 16:05:00 -1000 Subject: [PATCH 28/71] Add SqlDB to skip --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 3 ++- .../fundamentals/openapi/samples/9.x/BuildTime/Skip.cs | 4 ++-- .../openapi/samples/9.x/BuildTime/csproj/MyTestApi.json | 6 ++++-- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index d4ec4e55b966..408bc777a8b2 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -66,7 +66,6 @@ $ cat obj/MyTestApi.json The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, title, endpoints, and more](https://learn.openapis.org/specification/structure.html). The first few lines of `obj/MyTestApi.json` file: - :::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" id="snippet_1" highlight="4-5"::: ## Customize build-time document generation @@ -129,6 +128,8 @@ In some scenarios, it's important to restrict certain code paths when the app's To prevent these code paths from being invoked by the build-time generation pipeline, they can be conditioned behind a check of the entry assembly: +~/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs + :::code language="csharp" source="~/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs" id="snippet_1" highlight="7-12"::: ## OpenAPI document cleanup diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs index dea8acfc35cb..911045105095 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs @@ -1,5 +1,5 @@ #if NEVER -// +#region snippet_1 using ControllerApi.Data; using Microsoft.EntityFrameworkCore; using System.Reflection; @@ -30,5 +30,5 @@ app.MapControllers(); app.Run(); -// +#endregion #endif diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json index 517a01a227e7..3408a6ff041a 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json @@ -1,3 +1,4 @@ +// { "openapi": "3.0.1", "info": { @@ -16,6 +17,7 @@ "description": "OK", "content": { "application/json": { + // "schema": { "type": "array", "items": { @@ -47,10 +49,10 @@ } } }, - "components": { }, + "components": {}, "tags": [ { "name": "GetDocument.Insider" } ] -} \ No newline at end of file +} From 1a1766d07bd3c52abd35d4f85a16482af84d2254 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 16:23:35 -1000 Subject: [PATCH 29/71] Add SqlDB to skip --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 2 +- .../openapi/samples/9.x/BuildTime/MyTestApi.csproj | 4 ++-- .../fundamentals/openapi/samples/9.x/BuildTime/Program.cs | 4 +++- .../openapi/samples/9.x/BuildTime/csproj/MyTestApi.json | 7 +++---- 4 files changed, 9 insertions(+), 8 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 408bc777a8b2..941765129b8a 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -66,7 +66,7 @@ $ cat obj/MyTestApi.json The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, title, endpoints, and more](https://learn.openapis.org/specification/structure.html). The first few lines of `obj/MyTestApi.json` file: -:::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" id="snippet_1" highlight="4-5"::: +:::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" range="1-15 highlight="4-5"::: ## Customize build-time document generation diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index d64b34531f20..5b4144c39638 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -6,9 +6,9 @@ enable - + diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs index dffeeae8a666..a2ce794f7330 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs @@ -2,7 +2,9 @@ var builder = WebApplication.CreateBuilder(); -builder.Services.AddAuthorization(); +if (Assembly.GetEntryAssembly()?.GetName().Name != "Crazy String") + + builder.Services.AddAuthorization(); // Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi builder.Services.AddOpenApi(); diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json index 3408a6ff041a..59f590244e0c 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json @@ -1,4 +1,3 @@ -// { "openapi": "3.0.1", "info": { @@ -17,9 +16,9 @@ "description": "OK", "content": { "application/json": { - // "schema": { "type": "array", + "items": { "type": "object", "properties": { @@ -49,10 +48,10 @@ } } }, - "components": {}, + "components": { }, "tags": [ { "name": "GetDocument.Insider" } ] -} +} \ No newline at end of file From 808fbb544585381a6b59522a296f0b4f84c2e413 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 16:31:59 -1000 Subject: [PATCH 30/71] Add SqlDB to skip --- .../fundamentals/openapi/buildtime-openapi.md | 2 +- .../samples/9.x/BuildTime/MyTestApi.json | 56 +++++++++++++++++++ 2 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 941765129b8a..12402186715a 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -66,7 +66,7 @@ $ cat obj/MyTestApi.json The generated `obj/{MyProjectName}.json` file contains the [OpenAPI version, title, endpoints, and more](https://learn.openapis.org/specification/structure.html). The first few lines of `obj/MyTestApi.json` file: -:::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" range="1-15 highlight="4-5"::: +:::code language="json" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json" range="1-15" highlight="4-5"::: ## Customize build-time document generation diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json new file mode 100644 index 000000000000..517a01a227e7 --- /dev/null +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.json @@ -0,0 +1,56 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "GetDocument.Insider | v1", + "version": "1.0.0" + }, + "paths": { + "/weatherforecast": { + "get": { + "tags": [ + "GetDocument.Insider" + ], + "operationId": "GetWeatherForecast", + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "format": "date" + }, + "temperatureC": { + "type": "integer", + "format": "int32" + }, + "temperatureF": { + "type": "integer", + "format": "int32" + }, + "summary": { + "type": "string", + "nullable": true + } + } + } + } + } + } + } + } + } + } + }, + "components": { }, + "tags": [ + { + "name": "GetDocument.Insider" + } + ] +} \ No newline at end of file From 21e62a2fe1a2e5b2414306289d928c3787713c36 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 17:22:54 -1000 Subject: [PATCH 31/71] Add SqlDB to skip --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 2 -- .../fundamentals/openapi/samples/9.x/BuildTime/Skip.cs | 2 +- .../openapi/samples/9.x/BuildTime/csproj/MyTestApi.json | 8 ++++---- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 12402186715a..b81135b38623 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -128,8 +128,6 @@ In some scenarios, it's important to restrict certain code paths when the app's To prevent these code paths from being invoked by the build-time generation pipeline, they can be conditioned behind a check of the entry assembly: -~/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs - :::code language="csharp" source="~/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs" id="snippet_1" highlight="7-12"::: ## OpenAPI document cleanup diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs index 911045105095..a9f5af125354 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs @@ -6,7 +6,7 @@ var builder = WebApplication.CreateBuilder(args); -if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider") +if (Assembly.GetEntryAssembly()?.GetName().Name != "MyTestApi") { builder.Services.AddDbContext(options => options.UseSqlServer(builder.Configuration.GetConnectionString("ControllerApiContext") diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json index 59f590244e0c..f443cfb8601e 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.json @@ -1,14 +1,14 @@ { "openapi": "3.0.1", "info": { - "title": "GetDocument.Insider | v1", + "title": "MyTestApi | v1", "version": "1.0.0" }, "paths": { "/weatherforecast": { "get": { "tags": [ - "GetDocument.Insider" + "MyTestApi" ], "operationId": "GetWeatherForecast", "responses": { @@ -51,7 +51,7 @@ "components": { }, "tags": [ { - "name": "GetDocument.Insider" + "name": "MyTestApi" } ] -} \ No newline at end of file +} From ee50266c480f7ed264cf73bd582a22d931cf33af Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 15 Aug 2024 17:35:34 -1000 Subject: [PATCH 32/71] Add SqlDB to skip --- .../fundamentals/openapi/samples/9.x/BuildTime/Program.cs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs index a2ce794f7330..97d78cd377bd 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs @@ -2,16 +2,14 @@ var builder = WebApplication.CreateBuilder(); -if (Assembly.GetEntryAssembly()?.GetName().Name != "Crazy String") +//if (Assembly.GetEntryAssembly()?.GetName().Name != "Crazy String") - builder.Services.AddAuthorization(); +builder.Services.AddAuthorization(); -// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi builder.Services.AddOpenApi(); var app = builder.Build(); -// Configure the HTTP request pipeline. if (app.Environment.IsDevelopment()) { app.MapOpenApi(); From 9f95b5722b290ba740a392db7a4a57ac40ab38d4 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Fri, 16 Aug 2024 07:01:42 -1000 Subject: [PATCH 33/71] Add SqlDB to skip --- .../samples/9.x/BuildTime/MyTestApi.csproj | 2 +- .../csproj/MyTestApi.csproj.html.txt | 39 ------------------- 2 files changed, 1 insertion(+), 40 deletions(-) delete mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html.txt diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index 5b4144c39638..d19a5b055c0c 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -7,7 +7,7 @@ - . + --document-name v2 diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html.txt b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html.txt deleted file mode 100644 index 8220518b49a7..000000000000 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.html.txt +++ /dev/null @@ -1,39 +0,0 @@ - - - - - --file-name my-open-api - - - - - - . - - - - - ../MyOpenApiDocs - - - - - - --document-name v2 - - - - - - . - --file-name my-open-api - --document-name v2 - - From b5d98eaf05376a80ec6a828ec29d8f502cd5408c Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Fri, 16 Aug 2024 07:04:05 -1000 Subject: [PATCH 34/71] Apply suggestions from code review Co-authored-by: Martin Costello --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 2 +- .../openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index b81135b38623..b493acb13224 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -12,7 +12,7 @@ uid: fundamentals/openapi/buildtime-openapi # Generate OpenAPI documents at build-time -In a typical web apps, OpenAPI documents are generated at run-time and served via an HTTP request to the app server. +In typical web apps, OpenAPI documents are generated at run-time and served via an HTTP request to the app server. Generating OpenAPI documentation during the app's build step can be useful for documentation that is: diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php index 8220518b49a7..33bbffbf070e 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php @@ -1,5 +1,5 @@ + + + --document-name v2 - + From 3e4eca57b42e6b861d3dabd749f49baf37dcbdb7 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 22 Aug 2024 07:58:25 -1000 Subject: [PATCH 65/71] fix script --- .../fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj index 3b3e64c39d65..a749c19167e1 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/MyTestApi.csproj @@ -15,7 +15,7 @@ - + true From ecc1640c19092f8c3cb42c4e3a9f3cac946e4ec2 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 22 Aug 2024 13:34:17 -1000 Subject: [PATCH 66/71] fix script --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 9 --------- .../openapi/samples/9.x/BuildTime/Program.cs | 2 +- 2 files changed, 1 insertion(+), 10 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index b493acb13224..2836f365c4b9 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -108,15 +108,6 @@ By default, the build-time document generator creates files for all documents th :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet_doc_name"::: - - ## Customize run-time behavior during build-time document generation OpenAPI document generation at build-time works by starting the app’s entry point with a temporary background server. This approach is necessary to produce accurate OpenAPI documents, as not all information can be statically analyzed. When the app’s entry point is invoked, any logic in the app’s startup is executed, including code that injects services into the DI container or reads from configuration. diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs index 47bd81625041..b6022eb507be 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Program.cs @@ -1,7 +1,7 @@ var builder = WebApplication.CreateBuilder(args); -// Add services to the container. builder.Services.AddOpenApi(); +builder.Services.AddOpenApi("v2"); var app = builder.Build(); From e607a142f3c9665f3483308634c5523ffc35c6a8 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 22 Aug 2024 13:43:45 -1000 Subject: [PATCH 67/71] react to feedback V2 --- .../BuildTime/TestScripts/upateProgram.ps1 | 55 +++++++++++++++---- 1 file changed, 44 insertions(+), 11 deletions(-) diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/upateProgram.ps1 b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/upateProgram.ps1 index 02f70bba46f2..bde9c6bb06bf 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/upateProgram.ps1 +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/upateProgram.ps1 @@ -18,11 +18,40 @@ dotnet add package Microsoft.Extensions.ApiDescription.Server --version 9.0.0-* $ProgramCSname = "Program.cs" -# Read the content of the program.cs file -$programContent = Get-Content -Path $ProgramCSname +$newContent = @' +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddOpenApi(); +builder.Services.AddOpenApi("v2"); + +var app = builder.Build(); + +if (app.Environment.IsDevelopment()) +{ + app.MapOpenApi(); +} + +app.UseHttpsRedirection(); + +var summaries = new[] +{ + "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" +}; + +app.MapGet("/weatherforecast", () => +{ + var forecast = Enumerable.Range(1, 5).Select(index => + new WeatherForecast + ( + DateOnly.FromDateTime(DateTime.Now.AddDays(index)), + Random.Shared.Next(-20, 55), + summaries[Random.Shared.Next(summaries.Length)] + )) + .ToArray(); + return forecast; +}) +.WithName("GetWeatherForecast"); -# Define the new MapGet code to be added -$newMapGetCode = @' app.MapGet("/v2/weatherforecast", (HttpContext httpContext) => { var forecast = Enumerable.Range(1, 5).Select(index => @@ -36,17 +65,21 @@ app.MapGet("/v2/weatherforecast", (HttpContext httpContext) => return forecast; }) .WithGroupName("v2"); -'@ -# Find the index of the line containing "app.Run();" -$runIndex = $programContent.IndexOf("app.Run();") +app.Run(); + +record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary) +{ + public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); +} +'@ -# Insert the new MapGet code just before the app.Run() statement -$updatedContent = $programContent[0..($runIndex-1)] + $newMapGetCode + $programContent[$runIndex..($programContent.Length-1)] +# Write the new content to the Program.cs file +Set-Content -Path $ProgramCSname -Value $newContent -# Write the updated content back to the program.cs file -Set-Content -Path $ProgramCSname -Value $updatedContent +Write-Host "Program.cs file has been updated successfully." +# -------------------------- #Write-Host "New MapGet code has been added successfully." dotnet build From c6cee5faaa92e2633868e3e820afd5006ff56155 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 22 Aug 2024 14:27:48 -1000 Subject: [PATCH 68/71] react to feedback V2 --- .../openapi/samples/9.x/BuildTime/Skip.cs | 4 +- .../samples/9.x/MyOpenApiDocs/MyTestApi.json | 56 ------------------- 2 files changed, 2 insertions(+), 58 deletions(-) delete mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/MyOpenApiDocs/MyTestApi.json diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs index a9f5af125354..4947e4711eb3 100644 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs +++ b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/Skip.cs @@ -1,5 +1,5 @@ #if NEVER -#region snippet_1 +// using ControllerApi.Data; using Microsoft.EntityFrameworkCore; using System.Reflection; @@ -30,5 +30,5 @@ app.MapControllers(); app.Run(); -#endregion +// #endif diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/MyOpenApiDocs/MyTestApi.json b/aspnetcore/fundamentals/openapi/samples/9.x/MyOpenApiDocs/MyTestApi.json deleted file mode 100644 index 3e53e477e1bc..000000000000 --- a/aspnetcore/fundamentals/openapi/samples/9.x/MyOpenApiDocs/MyTestApi.json +++ /dev/null @@ -1,56 +0,0 @@ -{ - "openapi": "3.0.1", - "info": { - "title": "MyTestApi | v1", - "version": "1.0.0" - }, - "paths": { - "/weatherforecast": { - "get": { - "tags": [ - "MyTestApi" - ], - "operationId": "GetWeatherForecast", - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "format": "date" - }, - "temperatureC": { - "type": "integer", - "format": "int32" - }, - "temperatureF": { - "type": "integer", - "format": "int32" - }, - "summary": { - "type": "string", - "nullable": true - } - } - } - } - } - } - } - } - } - } - }, - "components": { }, - "tags": [ - { - "name": "MyTestApi" - } - ] -} \ No newline at end of file From b798c9a40596235426bbf68f8ea9c0dbdff6ab75 Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Thu, 22 Aug 2024 15:01:37 -1000 Subject: [PATCH 69/71] react to feedback V2 --- aspnetcore/fundamentals/openapi/buildtime-openapi.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/aspnetcore/fundamentals/openapi/buildtime-openapi.md b/aspnetcore/fundamentals/openapi/buildtime-openapi.md index 2836f365c4b9..85fee3088975 100644 --- a/aspnetcore/fundamentals/openapi/buildtime-openapi.md +++ b/aspnetcore/fundamentals/openapi/buildtime-openapi.md @@ -108,6 +108,7 @@ By default, the build-time document generator creates files for all documents th :::code language="xml" source="~/fundamentals/openapi/samples/9.x/BuildTime/csproj/MyTestApi.csproj.php" id="snippet_doc_name"::: + ## OpenAPI document cleanup From 8a0df43ba65cc7c5ceb3765f76e30ac40996b6bb Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Tue, 3 Sep 2024 13:38:21 -1000 Subject: [PATCH 70/71] react to feedback V2 --- .../9.x/BuildTime/TestScripts/{upateProgram.ps1 => v2.ps1} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/{upateProgram.ps1 => v2.ps1} (100%) diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/upateProgram.ps1 b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/v2.ps1 similarity index 100% rename from aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/upateProgram.ps1 rename to aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/v2.ps1 From 627672799aba1347ae68dad10e17bc70ad08bb2a Mon Sep 17 00:00:00 2001 From: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> Date: Tue, 3 Sep 2024 13:46:11 -1000 Subject: [PATCH 71/71] react to feedback V2 --- .../9.x/BuildTime/TestScripts/AdotDash.ps1 | 39 ------ .../9.x/BuildTime/TestScripts/doc_name.ps1 | 45 ------- .../9.x/BuildTime/TestScripts/file_name.ps1 | 40 ------- .../samples/9.x/BuildTime/TestScripts/v2.ps1 | 111 ------------------ 4 files changed, 235 deletions(-) delete mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/AdotDash.ps1 delete mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/doc_name.ps1 delete mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/file_name.ps1 delete mode 100644 aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/v2.ps1 diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/AdotDash.ps1 b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/AdotDash.ps1 deleted file mode 100644 index 38b5d430fadd..000000000000 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/AdotDash.ps1 +++ /dev/null @@ -1,39 +0,0 @@ -cls -$originalDir = Get-Location -cd C:\tmp -$Inner_text = "." # "./" fails on Windows, but works on Linux/Mac -$ProgramName = "MyOpenApiTest" -$Project = "$ProgramName.csproj" -$JsonFile = "$ProgramName.json" - -if (Test-Path $ProgramName) { - Write-Host "Removing existing '$ProgramName' directory..." - Remove-Item $ProgramName -Recurse -Force -} - -dotnet new webapi -n $ProgramName -Set-Location $ProgramName -dotnet add package Microsoft.Extensions.ApiDescription.Server --version 9.0.0-* --source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet9/nuget/v3/index.json - -dotnet build -# show output is in the obj directory -Select-String -Path "obj\$JsonFile" -Pattern "." | Select-Object -First 5 - -# Add property and test build with new property - -$xml = [xml](Get-Content $Project) -$newPropGrp1 = $xml.CreateElement("PropertyGroup") - -$newElement = $xml.CreateElement("OpenApiDocumentsDirectory") -$newElement.InnerText = $Inner_text -$newPropGrp1.AppendChild($newElement) - -$xml.Project.AppendChild($newPropGrp1) -$xml.OuterXml | Set-Content -Path $Project - -dotnet build - -Select-String -Path "obj\$JsonFile" -Pattern "." | Select-Object -First 5 - -Set-Location -Path $originalDir - diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/doc_name.ps1 b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/doc_name.ps1 deleted file mode 100644 index 0ce71dcac2eb..000000000000 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/doc_name.ps1 +++ /dev/null @@ -1,45 +0,0 @@ -# Yields error Document with name 'v2' not found. -# This script is similar to updateProgram.ps1, but it doesn't add the v2 endpoint -cls -$originalDir = Get-Location -cd C:\tmp -$ProgramName = "MyOpenApiTest" -# remove build from last run -if (Test-Path $ProgramName) { - Write-Host "Removing existing '$ProgramName' directory..." - Remove-Item $ProgramName -Recurse -Force -} -$Project = "$ProgramName.csproj" -dotnet new webapi -n $ProgramName -Set-Location $ProgramName - -dotnet add package Microsoft.Extensions.ApiDescription.Server --version 9.0.0-* --source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet9/nuget/v3/index.json - -dotnet build -if ($LASTEXITCODE -eq 0) { - Write-Output "Build succeeded." -} else { - Write-Output "Build failed." -} -# Add property and test build with new property -$xml = [xml](Get-Content $Project) -$newPropGrp1 = $xml.CreateElement("PropertyGroup") - -$newElement = $xml.CreateElement("OpenApiGenerateDocumentsOptions") -$newElement.InnerText = "--document-name v2" -$newPropGrp1.AppendChild($newElement) - -$xml.Project.AppendChild($newPropGrp1) -$xml.OuterXml | Set-Content -Path $Project - -dotnet build -if ($LASTEXITCODE -eq 0) { - Write-Output "Build succeeded." - Select-String -Path "obj\$ProgramName.json" -Pattern "." | Select-Object -First 5 - } -else { - Write-Output "Build failed." -} - -Set-Location -Path $originalDir - diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/file_name.ps1 b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/file_name.ps1 deleted file mode 100644 index e12bfc0eeb8b..000000000000 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/file_name.ps1 +++ /dev/null @@ -1,40 +0,0 @@ -# Creates a Web API project, adds ApiDescription.Server -cls -$originalDir = Get-Location -cd C:\tmp -$ProgramName = "MyOpenApiTest" -# remove build from last run -if (Test-Path $ProgramName) { - Write-Host "Removing existing '$ProgramName' directory..." - Remove-Item $ProgramName -Recurse -Force -} -$Project = "$ProgramName.csproj" - -dotnet new webapi -n $ProgramName -Set-Location $ProgramName -dotnet add package Microsoft.Extensions.ApiDescription.Server --version 9.0.0-* --source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet9/nuget/v3/index.json - -dotnet build - -# Add property and test build with new property -$xml = [xml](Get-Content $Project) -$newPropGrp1 = $xml.CreateElement("PropertyGroup") - -$newOpenApiName = "my-open-api" -$newElement = $xml.CreateElement("OpenApiGenerateDocumentsOptions") -$newElement.InnerText = "--file-name $newOpenApiName" -$newPropGrp1.AppendChild($newElement) - -$xml.Project.AppendChild($newPropGrp1) -$xml.OuterXml | Set-Content -Path $Project - -dotnet build - -# Select-String -Path "obj\$newOpenApiName.json" -Pattern "." | Select-Object -First 5 -$command -$command = "Select-String -Path 'obj/$newOpenApiName.json' -Pattern '.' | Select-Object -First 5" -$command | Invoke-Expression - -$command | Invoke-Expression | Out-Host # must run twice to see output - -Set-Location -Path $originalDir diff --git a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/v2.ps1 b/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/v2.ps1 deleted file mode 100644 index bde9c6bb06bf..000000000000 --- a/aspnetcore/fundamentals/openapi/samples/9.x/BuildTime/TestScripts/v2.ps1 +++ /dev/null @@ -1,111 +0,0 @@ -# Yields error Document with name 'v2' not found. -# This script is similar to updateProgram.ps1, but it adds thee v2 endpoint -cls -$originalDir = Get-Location -cd C:\tmp -$ProgramName = "MyOpenApiTest" -# remove build from last run -if (Test-Path $ProgramName) { - Write-Host "Removing existing '$ProgramName' directory..." - Remove-Item $ProgramName -Recurse -Force -} -$Project = "$ProgramName.csproj" - -dotnet new webapi -n $ProgramName - -Set-Location $ProgramName -dotnet add package Microsoft.Extensions.ApiDescription.Server --version 9.0.0-* --source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet9/nuget/v3/index.json - -$ProgramCSname = "Program.cs" - -$newContent = @' -var builder = WebApplication.CreateBuilder(args); - -builder.Services.AddOpenApi(); -builder.Services.AddOpenApi("v2"); - -var app = builder.Build(); - -if (app.Environment.IsDevelopment()) -{ - app.MapOpenApi(); -} - -app.UseHttpsRedirection(); - -var summaries = new[] -{ - "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" -}; - -app.MapGet("/weatherforecast", () => -{ - var forecast = Enumerable.Range(1, 5).Select(index => - new WeatherForecast - ( - DateOnly.FromDateTime(DateTime.Now.AddDays(index)), - Random.Shared.Next(-20, 55), - summaries[Random.Shared.Next(summaries.Length)] - )) - .ToArray(); - return forecast; -}) -.WithName("GetWeatherForecast"); - -app.MapGet("/v2/weatherforecast", (HttpContext httpContext) => -{ - var forecast = Enumerable.Range(1, 5).Select(index => - new WeatherForecast - ( - DateOnly.FromDateTime(DateTime.Now.AddDays(index)), - Random.Shared.Next(-20, 55), - summaries[Random.Shared.Next(summaries.Length)] - )) - .ToArray(); - return forecast; -}) -.WithGroupName("v2"); - -app.Run(); - -record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary) -{ - public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); -} -'@ - -# Write the new content to the Program.cs file -Set-Content -Path $ProgramCSname -Value $newContent - -Write-Host "Program.cs file has been updated successfully." - -# -------------------------- -#Write-Host "New MapGet code has been added successfully." - -dotnet build -if ($LASTEXITCODE -eq 0) { - Write-Output "Build succeeded." -} else { - Write-Output "Build failed." -} -# Add property and test build with new property -$xml = [xml](Get-Content $Project) -$newPropGrp1 = $xml.CreateElement("PropertyGroup") - -$newElement = $xml.CreateElement("OpenApiGenerateDocumentsOptions") -$newElement.InnerText = "--document-name v2" -$newPropGrp1.AppendChild($newElement) - -$xml.Project.AppendChild($newPropGrp1) -$xml.OuterXml | Set-Content -Path $Project - -dotnet build -if ($LASTEXITCODE -eq 0) { - Write-Output "Build succeeded." - Select-String -Path "obj\$ProgramName.json" -Pattern "." | Select-Object -First 5 -} -else { - Write-Output "Build failed." -} - -Set-Location -Path $originalDir