You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In a typical web applications, OpenAPI documents are generated at run-time and served via an HTTP request to the application server.
14
+
In typical web applications, OpenAPI documents are generated at run-time and served via an HTTP request to the application server.
15
15
16
-
In some scenarios, it is helpful to generate the OpenAPI document during the application's build step. These scenarios including:
16
+
In some scenarios, it's helpful to generate the OpenAPI document during the application's build step. These scenarios include:
17
17
18
-
- Generating OpenAPI documentation that is committed into source control
19
-
- Generating OpenAPI documentation that is used for spec-based integration testing
20
-
- Generating OpenAPI documentation that is served statically from the web server
18
+
- Generating OpenAPI documentation that is committed into source control.
19
+
- Generating OpenAPI documentation that is used for spec-based integration testing.
20
+
- Generating OpenAPI documentation that is served statically from the web server.
21
21
22
22
To add support for generating OpenAPI documents at build time, install the `Microsoft.Extensions.ApiDescription.Server` package:
23
23
@@ -42,7 +42,7 @@ Upon installation, this package will automatically generate the Open API documen
42
42
43
43
```cli
44
44
$ dotnet build
45
-
$ cat bin/Debub/net9.0/{ProjectName}.json
45
+
$ cat bin/Debug/net9.0/{ProjectName}.json
46
46
```
47
47
48
48
## Customizing build-time document generation
@@ -83,8 +83,8 @@ Some applications may be configured to emit multiple OpenAPI documents, for vari
83
83
84
84
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:
85
85
86
-
- Not reading from certain configuration strings
87
-
- Not registering database-related services
86
+
- Not reading from certain configuration strings.
87
+
- Not registering database-related services.
88
88
89
89
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:
90
90
@@ -95,6 +95,6 @@ var builder = WebApplication.CreateBuilder();
95
95
96
96
if (Assembly.GetEntryAssembly()?.GetName().Name!="GetDocument.Insider")
0 commit comments