Enhance routef support for named parameters and improve documentation (#656)

* fix: enhance getConstraint function to handle optional name parameter

* docs: add handler for petId endpoint to sample

* test: add routef test for named parameter in pet endpoint

* docs: add support for named parameters in routef documentation

* Apply fantomas

* Add more unit tests

* Fix formatting

* Update tests/Giraffe.Tests/EndpointRoutingTests.fs

* Fix formatting and add new test scenarios

---------

Co-authored-by: Vinícius Gajo <[email protected]>
Co-authored-by: 64J0 <[email protected]>

Author: RJSonnenberg

DOCUMENTATION.md

@@ -1089,6 +1089,9 @@ let fooHandler (first : string,
 
 let webApp =
     choose [
+        // Named parameter example:
+        routef "/pet/%i:petId" (fun (petId: int) -> text (sprintf "PetId: %i" petId))
+        // Classic usage:
         routef "/foo/%s/%s/%i" fooHandler
         routef "/bar/%O" (fun guid -> text (guid.ToString()))
 
@@ -1099,7 +1102,7 @@ let webApp =
 
 The `routef` http handler takes two parameters - a format string and an `HttpHandler` function.
 
-The format string supports the following format chars:
+The format string supports the following format chars, and now also supports **named parameters** using the syntax `%c:name` (e.g. `%i:petId`):
 
 | Format Char | Type |
 | ----------- | ---- |
@@ -1112,6 +1115,8 @@ The format string supports the following format chars:
 | `%O` | `Guid` (including short GUIDs*) |
 | `%u` | `uint64` (formatted as a short ID*) |
 
+**Named parameters**: You can use `%c:name` to assign a name to a route parameter, which is especially useful for OpenAPI/Swagger documentation and for clarity. For example, `routef "/pet/%i:petId"` will match `/pet/42` and bind `petId` to `42`.
+
 *) Please note that the `%O` and `%u` format characters also support URL friendly short GUIDs and IDs.
 
 The `%O` format character supports GUIDs in the format of:

samples/EndpointRoutingApp/Program.fs

@@ -18,13 +18,17 @@ let handler2 (firstName: string, age: int) : HttpHandler =
 let handler3 (a: string, b: string, c: string, d: int) : HttpHandler =
     fun (_: HttpFunc) (ctx: HttpContext) -> sprintf "Hello %s %s %s %i" a b c d |> ctx.WriteTextAsync
 
+let handlerNamed (petId: int) : HttpHandler =
+    fun (_: HttpFunc) (ctx: HttpContext) -> sprintf "PetId: %i" petId |> ctx.WriteTextAsync
+
 let endpoints =
     [
         subRoute "/foo" [ GET [ route "/bar" (text "Aloha!") ] ]
         GET [
             route "/" (text "Hello World")
             routef "/%s/%i" handler2
             routef "/%s/%s/%s/%i" handler3
+            routef "/pet/%i:petId" handlerNamed
         ]
         GET_HEAD [
             route "/foo" (text "Bar")

src/Giraffe/EndpointRouting.fs

@@ -21,8 +21,8 @@ module RouteTemplateBuilder =
 
     let private shortIdPattern = "([-_0-9A-Za-z]{{10}}[048AEIMQUYcgkosw])"
 
-    let private getConstraint (i: int) (c: char) =
-        let name = sprintf "%c%i" c i
+    let private getConstraint (i: int) (c: char) (name: string option) =
+        let name = Option.defaultValue (sprintf "%c%i" c i) name
 
         match c with
         | 'b' -> name, sprintf "{%s:bool}" name // bool
@@ -42,9 +42,29 @@ module RouteTemplateBuilder =
                 let template, mappings = convert i tail
                 "%" + template, mappings
             | '%' :: c :: tail ->
-                let template, mappings = convert (i + 1) tail
-                let placeholderName, placeholderTemplate = getConstraint i c
-                placeholderTemplate + template, (placeholderName, c) :: mappings
+                match tail with
+                | ':' :: stail ->
+                    let splitIndex = stail |> List.tryFindIndex (fun c -> c = '/')
+
+                    match splitIndex with
+                    | Some splitIndex ->
+                        let name, newTail = stail |> List.splitAt splitIndex
+
+                        let placeholderName, placeholderTemplate =
+                            getConstraint i c (Some(System.String.Concat(Array.ofList (name))))
+
+                        let template, mappings = convert (i + 1) newTail
+                        placeholderTemplate + template, (placeholderName, c) :: mappings
+                    | None ->
+                        let placeholderName, placeholderTemplate =
+                            getConstraint i c (Some(System.String.Concat(Array.ofList (stail))))
+
+                        let template, mappings = convert (i + 1) []
+                        placeholderTemplate + template, (placeholderName, c) :: mappings
+                | _ ->
+                    let placeholderName, placeholderTemplate = getConstraint i c None
+                    let template, mappings = convert (i + 1) tail
+                    placeholderTemplate + template, (placeholderName, c) :: mappings
             | c :: tail ->
                 let template, mappings = convert i tail
                 c.ToString() + template, mappings

tests/Giraffe.Tests/EndpointRoutingTests.fs

@@ -151,3 +151,105 @@ let ``subRouteWithExtensions: GET request returns expected result`` (path: strin
 
         content |> shouldEqual expected
     }
+
+[<Theory>]
+[<InlineData("/pet/42", "PetId: 42")>]
+[<InlineData("/pet/0", "PetId: 0")>]
+[<InlineData("/pet/123", "PetId: 123")>]
+[<InlineData("/pet/-1", "PetId: -1")>]
+[<InlineData("/pet/abc", "Not Found")>]
+[<InlineData("/pet/123abc", "Not Found")>]
+[<InlineData("/pet/123.456", "Not Found")>]
+[<InlineData("/pet/123-456", "Not Found")>]
+let ``routef: GET "/pet/%i:petId" returns named parameter`` (path: string, expected: string) =
+    task {
+        let endpoints: Endpoint list =
+            [
+                GET [ routef "/pet/%i:petId" (fun (petId: int) -> text ($"PetId: {petId}")) ]
+                GET [
+                    routef
+                        "/foo/%i/bar/%i:barId"
+                        (fun (fooId: int, barId: int) -> text ($"FooId: {fooId}, BarId: {barId}"))
+                ]
+            ]
+
+        let notFoundHandler = "Not Found" |> text |> RequestErrors.notFound
+
+        let configureApp (app: IApplicationBuilder) =
+            app.UseRouting().UseGiraffe(endpoints).UseGiraffe(notFoundHandler)
+
+        let configureServices (services: IServiceCollection) =
+            services.AddRouting().AddGiraffe() |> ignore
+
+        let request = createRequest HttpMethod.Get path
+
+        let! response = makeRequest (fun () -> configureApp) configureServices () request
+        let! content = response |> readText
+        content |> shouldEqual expected
+    }
+
+[<Theory>]
+[<InlineData("/foo/123/bar/abc", "FooId: 123, BarId: abc")>]
+[<InlineData("/foo/999/bar/789", "FooId: 999, BarId: 789")>]
+[<InlineData("/foo/-1/bar/123", "FooId: -1, BarId: 123")>]
+[<InlineData("/foo/abc/bar/def", "Not Found")>]
+let ``routef: GET "/foo/%i:fooId/bar/%i" returns named and unnamed parameters`` (path: string, expected: string) =
+    task {
+        let endpoints: Endpoint list =
+            [
+                GET [
+                    routef
+                        "/foo/%i:fooId/bar/%s:barId"
+                        (fun (fooId: int, barId: string) -> text ($"FooId: {fooId}, BarId: {barId}"))
+                ]
+            ]
+
+        let notFoundHandler = "Not Found" |> text |> RequestErrors.notFound
+
+        let configureApp (app: IApplicationBuilder) =
+            app.UseRouting().UseGiraffe(endpoints).UseGiraffe(notFoundHandler)
+
+        let configureServices (services: IServiceCollection) =
+            services.AddRouting().AddGiraffe() |> ignore
+
+        let request = createRequest HttpMethod.Get path
+
+        let! response = makeRequest (fun () -> configureApp) configureServices () request
+        let! content = response |> readText
+        content |> shouldEqual expected
+    }
+
+[<Theory>]
+[<InlineData("/foo/123/bar/000/baz/aaa", "FooId: 123, BarId: 0, BazName: aaa")>]
+[<InlineData("/foo/999/bar/789/baz/bbb", "FooId: 999, BarId: 789, BazName: bbb")>]
+[<InlineData("/foo/-1/bar/123/baz/ccc", "FooId: -1, BarId: 123, BazName: ccc")>]
+[<InlineData("/foo/abc/bar/v01/baz/ddd", "Not Found")>]
+let ``routef: GET "/foo/%i:fooId/bar/%i/baz/%s" returns named and unnamed parameters``
+    (path: string, expected: string)
+    =
+    task {
+        let endpoints: Endpoint list =
+            [
+                GET [
+                    routef
+                        "/foo/%i:fooId/bar/%i/baz/%s"
+                        (fun (fooId: int, barId: int, bazName: string) ->
+                            text ($"FooId: {fooId}, BarId: {barId}, BazName: {bazName}")
+                        )
+                ]
+            ]
+
+        let notFoundHandler = "Not Found" |> text |> RequestErrors.notFound
+
+        let configureApp (app: IApplicationBuilder) =
+            app.UseRouting().UseGiraffe(endpoints).UseGiraffe(notFoundHandler)
+
+        let configureServices (services: IServiceCollection) =
+            services.AddRouting().AddGiraffe() |> ignore
+
+        let request = createRequest HttpMethod.Get path
+
+        let! response = makeRequest (fun () -> configureApp) configureServices () request
+        let! content = response |> readText
+        content |> shouldEqual expected
+    }