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
Some of the changes you will see in the generated OpenAPI document include:
14
-
- Nullable types will no longer have the `nullable: true` property in the schema, and instead will have a `type` keyword whose value is an array that includes `null` as one of the types.
15
11
16
-
With this feature, the default OpenAPI version for generated documents will be 3.1, but you can easily change this
17
-
by explicitly setting the `OpenApiVersion` property of the `OpenApiOptions` in the `configureOptions` delegate
18
-
parameter of `AddOpenApi`.
12
+
- Nullable types no longer have the `nullable: true` property in the schema.
13
+
- Instead of a `nullable: true` property, they have a `type` keyword whose value is an array that includes `null` as one of the types.
14
+
15
+
With this feature, the default OpenAPI version for generated documents is`3.1`. The version can be changed by explicitly setting the [OpenApiVersion](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions.openapiversion) property of the [OpenApiOptions](/dotnet/api/microsoft.aspnetcore.openapi.openapioptions) in the `configureOptions` delegate parameter of [AddOpenApi](/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi).
If you are generating the OpenAPI document at build time, you can select the OpenAPI version by setting the `--openapi-version` in the `OpenApiGenerateDocumentsOptions` MSBuild item.
25
+
When generating the OpenAPI document at build time, the OpenAPI version can be selected by setting the `--openapi-version` in the `OpenApiGenerateDocumentsOptions` MSBuild item.
29
26
30
27
```xml
31
28
<!-- Configure build-time OpenAPI generation to produce an OpenAPI 3.0 document. -->
OpenAPI 3.1 support was primarly added in the following [PR](https://github.com/dotnet/aspnetcore/pull/59480).
33
+
34
+
### OpenAPI 3.1 breaking changes
35
+
36
+
Support for OpenAPI 3.1 requires an update to the underlying OpenAPI.NET library to a new major version, 2.0. This new version has some breaking changes from the previous version. The breaking changes may impact apps if they have any document, operation, or schema transformers.
36
37
37
-
Support for OpenAPI 3.1 requires an update to the underlying OpenAPI.NET library to a new major version, 2.0.
38
-
This new version has some breaking changes from the previous version, and this may impact your applications
39
-
if you have any document, operation, or schema transformers.
40
-
Perhaps the most significant change is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly.
41
-
If your transformers use `OpenApiAny`, you will need to update them to use `JsonNode` instead.
42
-
For example, a schema transformer to add an example in .NET 9 might look like this:
38
+
One of the most significant changes is that the `OpenApiAny` class has been dropped in favor of using `JsonNode` directly. Transformers that use `OpenApiAny` need to be updated to use `JsonNode`. For example, a schema transformer to add an example in .NET 9 might look like the following code:
Note that these changes are necessary even when only congfiguring the OpenAPI version to 3.0.
85
101
86
-
ASP.NET now supports serving the generated OpenAPI document in YAML format.
87
-
YAML can be more concise than JSON, eliminating curly braces and quotation marks when these can be inferred.
88
-
YAML also supports multi-line strings, which can be useful for long descriptions.
102
+
### OpenAPI in Yaml
89
103
90
-
To configure your application to serve the generated OpenAPI document in YAML format,
91
-
specify the endpoint in the MapOpenApi call with a ".yaml" or ".yml" suffix, as shown in this example:
104
+
ASP.NET now supports serving the generated OpenAPI document in YAML format. YAML can be more concise than JSON, eliminating curly braces and quotation marks when these can be inferred. YAML also supports multi-line strings, which can be useful for long descriptions.
105
+
106
+
To configure an app to serve the generated OpenAPI document in YAML format, specify the endpoint in the MapOpenApi call with a ".yaml" or ".yml" suffix, as shown in the following example:
92
107
93
108
```csharp
94
109
app.MapOpenApi("/openapi/{documentName}.yaml");
95
110
```
96
111
97
-
Support for YAML is currently only available for the the OpenAPI served from the OpenAPI endpoint.
98
-
Support for generating OpenAPI documents in YAML format at build time will be added in a future preview.
112
+
Support for:
113
+
114
+
- YAML is currently only available for the the OpenAPI served from the OpenAPI endpoint.
115
+
- Generating OpenAPI documents in YAML format at build time isadded in a future preview.
116
+
117
+
See [this PR](https://github.com/dotnet/aspnetcore/pull/58616) which added support for serving the generated OpenAPI document in YAML format.
The ProducesAttribute, ProducesResponseTypeAttribute, and ProducesDefaultResponseType attributes now accept an optional string parameter, `Description`, that will set the description of the response. Here's an example:
3
+
The [ProducesAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesattribute-1), [ProducesResponseTypeAttribute](/dotnet/api/microsoft.aspnetcore.mvc.producesresponsetypeattribute-1), and [ProducesDefaultResponseType](/dotnet/api/microsoft.aspnetcore.mvc.producesdefaultresponsetypeattribute) attributes now accept an optional string parameter, `Description`, that will set the description of the response. Here's an example:
6
4
7
5
```csharp
8
6
[HttpGet(Name="GetWeatherForecast")]
@@ -11,7 +9,7 @@ public IEnumerable<WeatherForecast> Get()
11
9
{
12
10
```
13
11
14
-
AndthegeneratedOpenAPIwillbe
12
+
AndthegeneratedOpenAPI:
15
13
16
14
```json
17
15
"responses": {
@@ -20,4 +18,4 @@ And the generated OpenAPI will be
20
18
"content": {
21
19
```
22
20
23
-
Communitycontribution! 🙏
21
+
[Communitycontribution](https://github.com/dotnet/aspnetcore/pull/58193) by [Sander ten Brinke](https://github.com/sander1095) 🙏
## Better support for testing apps with top-level statements
2
2
3
-
https://github.com/dotnet/aspnetcore/pull/58199
4
-
https://github.com/dotnet/aspnetcore/pull/58482
3
+
.NET 10 now has better support for testing apps that use top-level statements. Previously developers had to manually add `public partial class Program` to the `Program.cs` file so that the test project could reference the `Program class`. This is because the top-level statement feature in C# 9 generated a `Program class` that was declared as internal.
5
4
6
-
.NET 10 now has better support for testing apps that use top-level statements.
7
-
Previously developers had to manually add `public partial class Program` to the
8
-
Program.cs file so that the test project could reference the Program class.
9
-
This is because the top-level statement feature in C# 9 generated a Program class
10
-
that was declared as internal.
5
+
In .NET 10, a source generator is used to generate the `public partial class Program` declaration if the programmer did not declare it explicitly. In addition, an analyzer was added to detect when `public partial class Program` is declared explicitly and advise the developer to remove it.
11
6
12
-
In .NET 10, a source generator is used to generate the `public partial class Program`
13
-
declaration if the programmer did not declare it explicitly. In addition, an analyzer
14
-
was added to detect when `public partial class Program` is declared explicitly and
0 commit comments