Add ability to Configure Endpoints via IEndpointConventionBuilder

[mrtz-j]

Description

This PR adds the ability to configure endpoints via the IEndpointConventionBuilder. This would enable us to reuse some of the built-in OpenApi generation to generate OpenApi schemas from code. It's possible by replacing the MetadataList with a ConfigureEndpoint, which can be utilized to capture additional information about the endpoint.

I've taken inspiration from Oxpeckers Routing which uses a similar approach.

How to test

A working example provided in the Giraffe.OpenApi repo, which utilizes this branch. It's based on the MinimalApi approach, with a more functional syntax.

|> configureEndpoint _.WithName("Endpoint")
|> withOpenApi<unit, string>

In the example Swagger has been used to display the configured endpoints.

Endpoints can be added to the OpenApi documentation as follows:

We have the type FsharpMessage, with XML-documentation:

/// <summary>
/// Fsharp Message type 
/// </summary>
type FsharpMessage = {
    /// <summary>
    /// Hello content
    /// </summary>
    /// <example>This is an Example</example>
    Hello: string
}

and the endpoints /hello

let endpoints = [
      GET [
            route "/hello" (json {Hello = "Hello from Giraffe"})
            |> configureEndpoint _.WithTags("helloGiraffe")
            |> configureEndpoint _.WithSummary("Fetches a Hello from Giraffe")
            |> configureEndpoint _.WithDescription("Will return a Hello from Giraffe.")
            |> addOpenApiSimple<unit, FsharpMessage>
]

which will be produce the view below:

Endpoint and Type in Swagger

And for extra references the whole app.

Swagger view of the endpoints.

If it's accepted, I'll either publish Giraffe.OpenApi or make another MR for it here.

Related issues

• #488

[nojaf]

Hello, thank you for this PR!

I can't review the code as I'm not suited enough for that. However, this looks interesting. If this gets accepted would you be ok with Giraffe.OpenApi being part of the organization here? Seems like an interesting addition to the family. Just thinking out loud though.

//cc @64J0, @dbrattli

[mrtz-j]

Hello, thank you for this PR!

I can't review the code as I'm not suited enough for that. However, this looks interesting. If this gets accepted would you be ok with Giraffe.OpenApi being part of the organization here? Seems like an interesting addition to the family. Just thinking out loud though.

//cc @64J0, @dbrattli

Hi there,

Yes, I would be fine with it being part of the organization.

[64J0]

Hi, thanks for the PR, seems pretty cool. I think I'll have some time to review it next week!

[voronoipotato]

Fantastic, looking at it I don't see any issues. Since this works it would mean a lot to many of us if this was merged.

[dbrattli]

Thanks for submitting this RP. I think this looks really great 😊 We should also update the documentation before merging. I'm trying to figure out if this is a breaking change or not i.e for applications upgrading Giraffe to a newer version of the library. The addMetadata function has the same signature but still has changed to a more/less "curried" form, but the original is still curried so should this matter?

val addMetadata:
   metadata: obj ->
   endpoint: Endpoint
          -> Endpoint

to

val addMetadata:
   metadata: obj
          -> Endpoint -> Endpoint

I don't think it's a breaking change 🙈 but I'll let someone who knows F# better than me decide if it makes sense to keep the exact same signature just to be sure i.e change to:

let addMetadata (metadata: obj) (endpoint: Endpoint)=
        endpoint |> configureEndpoint _.WithMetadata(metadata)

[64J0]

Since it's dealing with a piece of code similar to what we have on Oxpecker, I'll ping @Lanayx so he knows about it too

[64J0]

Tested the sample application locally, and it's working as described. Great PR!

Regarding the addMetadata signature change pointed by @dbrattli, I agree that it's not a breaking change. I also agree that it would be nice to have the documentation updated. Would you like to do it @mrtz-j?

[mrtz-j]

I've updated the addMetadata function to match the previous signature just in case 😅. I'd also be up for writing some documentation over the weekend, but it's also fine if one of you guys wants to.

[nojaf]

Thanks for the review @64J0. Can we ship this as an alpha?

[64J0]

Thanks for the review @64J0. Can we ship this as an alpha?

Sure @nojaf! I'll do it either today or tomorrow.