Skip to content

Commit 858fb42

Browse files
Clean up moniker hell (#35255)
* Clean up moniker hell * Clean up moniker hell * Clean up moniker hell
1 parent 65223e4 commit 858fb42

File tree

2 files changed

+593
-52
lines changed

2 files changed

+593
-52
lines changed

aspnetcore/fundamentals/openapi/include-metadata.md

Lines changed: 8 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ uid: fundamentals/openapi/include-metadata
1212

1313
## Include OpenAPI metadata for endpoints
1414

15+
:::moniker range=">= aspnetcore-10.0"
16+
1517
ASP.NET collects metadata from the web app's endpoints and uses it to generate an OpenAPI document.
1618
In controller-based apps, metadata is collected from attributes like [`[EndpointDescription]`](xref:Microsoft.AspNetCore.Http.EndpointDescriptionAttribute), [`[HttpPost]`](xref:Microsoft.AspNetCore.Mvc.HttpPostAttribute),
1719
and [`[Produces]`](xref:Microsoft.AspNetCore.Mvc.ProducesAttribute).
@@ -314,8 +316,6 @@ app.MapGet("/todos",
314316
async (TodoDb db) => await db.Todos.ToListAsync());
315317
```
316318

317-
:::moniker range=">= aspnetcore-10.0"
318-
319319
[`[ProducesResponseType]`](xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute), [`[Produces]`](xref:Microsoft.AspNetCore.Mvc.ProducesAttribute), and [`[ProducesDefaultResponseType]`](xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute) also support an optional string property called `Description` that can be used to describe the response. This is useful for explaining why or when clients can expect a specific response:
320320

321321
```csharp
@@ -327,8 +327,6 @@ app.MapGet("/todos/{id}",
327327
async (int id, TodoDb db) => /* Code here */);
328328
```
329329

330-
:::moniker-end
331-
332330
Using <xref:Microsoft.AspNetCore.Http.TypedResults> in the implementation of an endpoint's route handler automatically includes the response type metadata for the endpoint. For example, the following code automatically annotates the endpoint with a response under the `200` status code with an `application/json` content type.
333331

334332
```csharp
@@ -398,8 +396,6 @@ Only one [`[Produces]`](xref:Microsoft.AspNetCore.Mvc.ProducesAttribute) or <xre
398396

399397
All of the above attributes can be applied to individual action methods or to the controller class where it applies to all action methods in the controller.
400398

401-
:::moniker range=">= aspnetcore-10.0"
402-
403399
[`[ProducesResponseType]`](xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute), [`[Produces]`](xref:Microsoft.AspNetCore.Mvc.ProducesAttribute), and [`[ProducesDefaultResponseType]`](xref:Microsoft.AspNetCore.Mvc.ProducesResponseTypeAttribute) also support an optional string property called `Description` that can be used to describe the response. This is useful for explaining why or when clients can expect a specific response:
404400

405401
```csharp
@@ -412,8 +408,6 @@ All of the above attributes can be applied to individual action methods or to th
412408
public async Task<ActionResult<Todo>> GetTodoItem(string id, Todo todo)
413409
```
414410

415-
:::moniker-end
416-
417411
When not specified by an attribute:
418412

419413
* The status code for the response defaults to 200.
@@ -493,39 +487,6 @@ of the property in the schema.
493487

494488
### type and format
495489

496-
:::moniker range="< aspnetcore-10.0"
497-
498-
The JSON Schema library maps standard C# types to OpenAPI `type` and `format` as follows:
499-
500-
| C# Type | OpenAPI `type` | OpenAPI `format` |
501-
| -------------- | -------------- | ---------------- |
502-
| int | integer | int32 |
503-
| long | integer | int64 |
504-
| short | integer | int16 |
505-
| byte | integer | uint8 |
506-
| float | number | float |
507-
| double | number | double |
508-
| decimal | number | double |
509-
| bool | boolean | |
510-
| string | string | |
511-
| char | string | char |
512-
| byte[] | string | byte |
513-
| DateTimeOffset | string | date-time |
514-
| DateOnly | string | date |
515-
| TimeOnly | string | time |
516-
| Uri | string | uri |
517-
| Guid | string | uuid |
518-
| object | _omitted_ | |
519-
| dynamic | _omitted_ | |
520-
521-
Note that object and dynamic types have _no_ type defined in the OpenAPI because these can contain data of any type, including primitive types like int or string.
522-
523-
The `type` and `format` can also be set with a [Schema Transformer](xref:fundamentals/openapi/customize-openapi#use-schema-transformers). For example, you may want the `format` of decimal types to be `decimal` instead of `double`.
524-
525-
:::moniker-end
526-
527-
:::moniker range=">= aspnetcore-10.0"
528-
529490
#### Numeric types
530491

531492
The JSON Schema library maps standard C# numeric types to OpenAPI `type` and `format` based on the
@@ -593,8 +554,6 @@ Other C# types are represented in the generated OpenAPI document as shown in the
593554
| object | _omitted_ | |
594555
| dynamic | _omitted_ | |
595556

596-
:::moniker-end
597-
598557
### Use attributes to add metadata
599558

600559
ASP.NET uses metadata from attributes on class or record properties to set metadata on the corresponding properties of the generated schema.
@@ -675,13 +634,6 @@ An enum type without a [`[JsonConverter]`](xref:System.Text.Json.Serialization.
675634

676635
#### nullable
677636

678-
:::moniker range="< aspnetcore-10.0"
679-
680-
Properties defined as a nullable value or reference type have `nullable: true` in the generated schema. This is consistent with the default behavior of the <xref:System.Text.Json> deserializer, which accepts `null` as a valid value for a nullable property.
681-
682-
:::moniker-end
683-
:::moniker range=">= aspnetcore-10.0"
684-
685637
Properties defined as a nullable value or reference type appear in the generated schema with a `type` keyword whose value is an array that includes `null` as one of the types. This is consistent with the default behavior of the <xref:System.Text.Json> deserializer, which accepts `null` as a valid value for a nullable property.
686638

687639
For example, a C# property defined as `string?` is represented in the generated schema as:
@@ -698,8 +650,6 @@ For example, a C# property defined as `string?` is represented in the generated
698650

699651
If the app is configured to produce OpenAPI v3.0 or OpenAPI v2 documents, nullable value or reference types have `nullable: true` in the generated schema because these OpenAPI versions do not allow the `type` field to be an array.
700652

701-
:::moniker-end
702-
703653
#### additionalProperties
704654

705655
Schemas are generated without an `additionalProperties` assertion by default, which implies the default of `true`. This is consistent with the default behavior of the <xref:System.Text.Json> deserializer, which silently ignores additional properties in a JSON object.
@@ -722,3 +672,9 @@ A schema transformer can be used to override any default metadata or add additio
722672

723673
* <xref:fundamentals/openapi/using-openapi-documents>
724674
* [OpenAPI specification](https://spec.openapis.org/oas/v3.0.3)
675+
676+
:::moniker-end
677+
678+
[!INCLUDE[](~/fundamentals/openapi/includes/include-metadata9.md)]
679+
680+
:::moniker-end

0 commit comments

Comments
 (0)