Swagger supports normal minimal asp.net core apis but not work for Giraffe endpoints

[albertwoo]

I am playing around with asp.net core 6.0.100-preview.6.21355.2
I found the swagger works for default endpoint routes like in below code the /hello2 will be picked by swagger, but not work with giraffe endpoints.

open System
open Microsoft.AspNetCore.Http
open Microsoft.AspNetCore.Builder
open Microsoft.Extensions.Hosting
open Microsoft.Extensions.DependencyInjection
open Giraffe
open Giraffe.EndpointRouting

let builder = WebApplication.CreateBuilder()

builder.Services.AddEndpointsApiExplorer()
builder.Services.AddHttpContextAccessor() |> ignore
builder.Services.AddSwaggerGen() |> ignore

let application = builder.Build()

application.UseSwagger() |> ignore
application.MapGiraffeEndpoints
    [
        GET [
            route "/hello1" (text "Hello")
        ]
    ]
application.MapGet("/hello2", Func<_, _>(fun (ctx: HttpContext) -> $"Hi {ctx.Request.Path}")) |> ignore
application.UseSwaggerUI() |> ignore

application.Run()

[albertwoo]

This root reason should be similar with falco:
pimbrouwers/Falco#49

[Numpsy]

This was mentioned in the talk at https://www.twitch.tv/videos/1092464368 yesterday (right at the end, and in relation to https://github.com/baronfel/Giraffe.EndpointRouting.OpenAPI I think).
It sounds from that like the requirements for the new MS stuff to work on its own are quite specific (I haven't tried using the new v6 stuff myself yet though)

[baronfel]

Yep I brought it up on purpose because I'd seen this discussion pop up again (and also I'm the Falco repo).

The relevant code in aspnetcore is here, the gist of which is to translate specifically minimal endpoints that are described by lambdas (or method groups) by their endpoint Metadata (which includes the reflection Method info) into ApiDescriptors.

This doesn't work for giraffe at all because composed endpoints don't match this pattern, so if we want to interop at the level that Swashbuckle does, we'd need to implement our own Apidescriptor provider that could create these same structures from giraffe apis. Swashbuckle would then be able to take our ApiDescription and generate the swagger doc from that.

That's where the fiddly work comes in, as far as I can see it.

Link to the brief video clip where I go over this is here

[jkone27]

this project was archived but could be helpful, at least for the openapi CE writer part?
https://github.com/akhansari/FSharp.OpenApi

[jkone27]

dotnet/aspnetcore#37098

[jkone27]

maybe something new can be tried with these updates on openapi and metadata?

https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-7-preview-4/

[voronoipotato]

This would be really helpful for companies that are reliant on openapi and swagger. @baronfel thanks for the work to describe this.

[captainsafia]

Coming across this issue from domaindrivendev/Swashbuckle.AspNetCore#2300.

This doesn't work for giraffe at all because composed endpoints don't match this pattern, so if we want to interop at the level that Swashbuckle does, we'd need to implement our own Apidescriptor provider that could create these same structures from giraffe apis. Swashbuckle would then be able to take our ApiDescription and generate the swagger doc from that.

@baronfel's recommendation here is exactly right. Providing a custom IApiDescriptionProvider interface is the pathway that frameworks should take in order to light up support for OpenAPI in ASP.NET Core. The IApiDescriptionProvider is essentially the middleman introspection layer that allows other tooling (like Swashbuckle, NSwag, or the new built-in OpenAPI support coming in .NET 9) to determine what metadata it should generate.

The link above points to minimal API's implementation (see here). There's also implementations for MVC (see here) and gRPC (see here) that can be used as examples.

[voronoipotato]

@captainsafia thank you so much for helping provide tangible examples. maybe one day if I can find the time I'll try and mess around with an implementation attempt. Having swagger for Giraffe would really help unify our C# and F# api descriptions.