Skip to content

Clean up moniker hell #35255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Rick-Anderson merged 3 commits into from
Apr 17, 2025
Merged

Clean up moniker hell #35255

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fa574e1
Clean up moniker hell
Rick-Anderson Apr 17, 2025
072ce58
Clean up moniker hell
Rick-Anderson Apr 17, 2025
e8af4c3
Clean up moniker hell
Rick-Anderson Apr 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 8 additions & 52 deletions aspnetcore/fundamentals/openapi/include-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ uid: fundamentals/openapi/include-metadata

## Include OpenAPI metadata for endpoints

:::moniker range=">= aspnetcore-10.0"

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

:::moniker range=">= aspnetcore-10.0"

[`[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:

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

:::moniker-end

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.

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

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.

:::moniker range=">= aspnetcore-10.0"

[`[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:

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

:::moniker-end

When not specified by an attribute:

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

### type and format

:::moniker range="< aspnetcore-10.0"

The JSON Schema library maps standard C# types to OpenAPI `type` and `format` as follows:

| C# Type | OpenAPI `type` | OpenAPI `format` |
| -------------- | -------------- | ---------------- |
| int | integer | int32 |
| long | integer | int64 |
| short | integer | int16 |
| byte | integer | uint8 |
| float | number | float |
| double | number | double |
| decimal | number | double |
| bool | boolean | |
| string | string | |
| char | string | char |
| byte[] | string | byte |
| DateTimeOffset | string | date-time |
| DateOnly | string | date |
| TimeOnly | string | time |
| Uri | string | uri |
| Guid | string | uuid |
| object | _omitted_ | |
| dynamic | _omitted_ | |

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.

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`.

:::moniker-end

:::moniker range=">= aspnetcore-10.0"

#### Numeric types

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

:::moniker-end

### Use attributes to add metadata

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

#### nullable

:::moniker range="< aspnetcore-10.0"

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.

:::moniker-end
:::moniker range=">= aspnetcore-10.0"

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.

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

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.

:::moniker-end

#### additionalProperties

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.
Expand All @@ -722,3 +672,9 @@ A schema transformer can be used to override any default metadata or add additio

* <xref:fundamentals/openapi/using-openapi-documents>
* [OpenAPI specification](https://spec.openapis.org/oas/v3.0.3)

:::moniker-end

[!INCLUDE[](~/fundamentals/openapi/includes/include-metadata9.md)]

:::moniker-end
Loading