Support F# option type in OpenApi schema generator

[Lanayx]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

OpenAPI support has recently been add in F# web frameworks (Oxpecker, Giraffe, Falco). However there is a problem, that F# option type is not respected well. Here is an example with Oxpecker:

open Microsoft.AspNetCore.Builder
open Microsoft.AspNetCore.Http
open Microsoft.Extensions.DependencyInjection
open Oxpecker
open Oxpecker.OpenApi

type MyModel = { Name: string; Age: int option }

let endpoints = GET [
    route "/myModel" <| %TypedResults.Ok { Name = "John"; Age = None }
        |> configureEndpoint _.WithName("MyModel")
        |> addOpenApiSimple<unit, MyModel>
]

[<EntryPoint>]
let main args =
    let builder = WebApplication.CreateBuilder(args)
    builder.Services.AddRouting().AddOxpecker().AddOpenApi() |> ignore
    let app = builder.Build()
    app.UseRouting().UseOxpecker(endpoints) |> ignore
    app.MapOpenApi() |> ignore
    app.Run()
    0 // Exit code

Generates the following schema:

{
  "openapi": "3.0.1",
  "info": {
    "title": "Empty | v1",
    "version": "1.0.0"
  },
  "paths": {
    "/myModel": {
      "get": {
        "tags": [
          "Empty"
        ],
        "operationId": "MyModel",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MyModel"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FSharpOptionOfint": {
        "pattern": "^-?(?:0|[1-9]\\d*)$",
        "type": "integer"
      },
      "MyModel": {
        "required": [
          "name",
          "age"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "$ref": "#/components/schemas/FSharpOptionOfint"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Empty"
    }
  ]
}

Describe the solution you'd like

I expect it to generate the same schema as with just int, but without making this field required:

{
  "openapi": "3.0.1",
  "info": {
    "title": "Empty | v1",
    "version": "1.0.0"
  },
  "paths": {
    "/myModel": {
      "get": {
        "tags": [
          "Empty"
        ],
        "operationId": "MyModel",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MyModel"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MyModel": {
        "required": [
          "name"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "integer",
            "format": "int32"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Empty"
    }
  ]
}

Additional context

Note that FSharp option is already respected by System.Text.Json.

ValueOption type should also be supported in the same way.

.NET SDK:
 Version:           9.0.101
 Commit:            eedb237549
 Workload version:  9.0.100-manifests.4a280210
 MSBuild version:   17.12.12+1cce77968

[captainsafia]

@Lanayx Thanks for filing this issue!

The OpenAPI implementation uses System.Text.Json's schema generation under the hood which follow's STJ's serialization semantics. To that end, I think your issue might be related to dotnet/runtime#55744.

Baring official support for F# DUs in STJ, I think having the dotnet/runtime#105769 API implemented might also help get the desired behavior here.

Let me know if this assessment makes sense to you!

For now, I'll stick this in the backlog. I'm hoping there will be progress on the STJ end here to make things a little easier.

[Lanayx]

@captainsafia Thanks for answering, but I don't want to generalize it to any DU at this point (untill STJ supports them). But as long as STJ supports fsharp options and value options, I'd expect them to be supported in OpenApi as well. I think it should be special cased just as NRT https://github.com/dotnet/aspnetcore/blob/main/src/OpenApi/src/Services/OpenApiGenerator.cs#L308

[captainsafia]

@Lanayx Have you experimented with using schema transformers to see if you can achieve the desired behavior? See these docs.

[Lanayx]

Thanks, I'll have a look. Still, if I manage to add the right transformer, this will fix the issue for Oxpecker, but not for any other F#-based generation.

[captainsafia]

@Lanayx Correct! If there's interest in the issue, the transformer implementation can serve as the basis for something we'd include by default.

[Lanayx]

@captainsafia I've tried transformer and now I'm not sure if it's possible to leverage it, since the first schema parameter already contains wrong schema node, so I can't "replace" it with a correct one. As for context, JsonTypeInfo and JsonPropertyInfo don't have setters, so I can't change them either.

options.AddSchemaTransformer(fun schema context ct ->
    let t = context.JsonTypeInfo.Type
    if t.IsGenericType && t.GetGenericTypeDefinition() = typedefof<Option<_>> then
       Console.WriteLine("Transforming Option")
    Task.CompletedTask
) |> ignore