Skip to content

Add ASP.NET Core OpenAPI documentation to README #24

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
desjoerd merged 3 commits into from
Nov 30, 2025
Merged

Add ASP.NET Core OpenAPI documentation to README #24

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b94f7e3
Initial plan
Copilot Nov 30, 2025
badf3d2
Add ASP.NET Core OpenAPI documentation to README.md
Copilot Nov 30, 2025
661a97a
Fix grammar: change it's to its
Copilot Nov 30, 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
35 changes: 31 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ A .NET library that provides an `OptionalValue<T>` type, representing a value th
| Package | Version |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [OptionalValues](https://www.nuget.org/packages/OptionalValues) | [![NuGet](https://img.shields.io/nuget/v/OptionalValues.svg)](https://www.nuget.org/packages/OptionalValues) |
| [OptionalValues.OpenApi](https://www.nuget.org/packages/OptionalValues.OpenApi) | [![NuGet](https://img.shields.io/nuget/v/OptionalValues.OpenApi.svg)](https://www.nuget.org/packages/OptionalValues.OpenApi) |
| [OptionalValues.Swashbuckle](https://www.nuget.org/packages/OptionalValues.Swashbuckle) | [![NuGet](https://img.shields.io/nuget/v/OptionalValues.Swashbuckle.svg)](https://www.nuget.org/packages/OptionalValues.Swashbuckle) |
| [OptionalValues.NSwag](https://www.nuget.org/packages/OptionalValues.NSwag) | [![NuGet](https://img.shields.io/nuget/v/OptionalValues.NSwag.svg)](https://www.nuget.org/packages/OptionalValues.NSwag) |
| [OptionalValues.DataAnnotations](https://www.nuget.org/packages/OptionalValues.DataAnnotations) | [![NuGet](https://img.shields.io/nuget/v/OptionalValues.DataAnnotations.svg)](https://www.nuget.org/packages/OptionalValues.DataAnnotations) |
Expand Down Expand Up @@ -95,8 +96,9 @@ dotnet add package OptionalValues.FluentValidation
- **Optional DataAnnotations**: An extension library that provides support for DataAnnotations validation attributes on `OptionalValue<T>` properties.
- **FluentValidation Extensions**: Provides extension methods to simplify the validation of `OptionalValue<T>` properties using FluentValidation.
- **OpenApi/Swagger Support**:
- **ASP.NET Core OpenAPI**: Support for ASP.NET Core's built-in OpenAPI support (Microsoft.AspNetCore.OpenApi) is available through the `OptionalValues.OpenApi` package. It provides a schema transformer to correctly handle `OptionalValue<T>` types.
- **Swashbuckle** Includes a custom data contract resolver for Swashbuckle to generate accurate OpenAPI/Swagger documentation.
- **NSwag**: Support for NSwag is available through the `OptionalValues.NSwag` package. It includes an `OptionalValueTypeMapper` to map the `OptionalValue<T>` to it's underlying type `T` in the generated OpenAPI schema.
- **NSwag**: Support for NSwag is available through the `OptionalValues.NSwag` package. It includes an `OptionalValueTypeMapper` to map the `OptionalValue<T>` to its underlying type `T` in the generated OpenAPI schema.
- **Patch Operation Support**: Ideal for API patch operations where fields can be updated to `null` or remain unchanged.

# Table of Contents
Expand All @@ -119,13 +121,15 @@ dotnet add package OptionalValues.FluentValidation
- [Respect nullable annotations](#respect-nullable-annotations)
- [Library support](#library-support)
- [ASP.NET Core](#aspnet-core)
- [Swashbuckle](#swashbuckle)
- [ASP.NET Core OpenAPI](#aspnet-core-openapi)
- [Installation](#installation-1)
- [NSwag](#nswag)
- [Swashbuckle](#swashbuckle)
- [Installation](#installation-2)
- [NSwag](#nswag)
- [Installation](#installation-3)
- [System.ComponentModel.DataAnnotations](#systemcomponentmodeldataannotations)
- [FluentValidation](#fluentvalidation)
- [Installation](#installation-3)
- [Installation](#installation-4)
- [Using OptionalRuleFor](#using-optionalrulefor)
- [How It Works](#how-it-works)
- [Example Usage](#example-usage)
Expand Down Expand Up @@ -345,6 +349,29 @@ builder.Services.AddControllers()
});
```

## ASP.NET Core OpenAPI

The `OptionalValues.OpenApi` package provides support for ASP.NET Core's built-in OpenAPI support (Microsoft.AspNetCore.OpenApi) to generate accurate OpenAPI documentation for `OptionalValue<T>` properties.

It correctly unwraps the `OptionalValue<T>` type and generates the appropriate schema for the underlying type `T`.

### Installation

Install the package using the .NET CLI:

```bash
dotnet add package OptionalValues.OpenApi
```

Configure the OpenAPI services to use the `OptionalValue<T>` schema transformer:

```csharp
builder.Services.AddOpenApi(options =>
{
options.AddOptionalValueSupport();
});
```

## Swashbuckle

The `OptionalValues.Swashbuckle` package provides a custom data contract resolver for Swashbuckle to generate accurate OpenAPI/Swagger documentation for `OptionalValue<T>` properties.
Expand Down