From 83dc7bc109409d945a75a906f73ced7fa098407b Mon Sep 17 00:00:00 2001
From: "Jeremy D. Miller" <jeremydmiller@yahoo.com>
Date: Mon, 17 Jul 2023 09:37:20 -0500
Subject: [PATCH] new docs for 1.2

---
 docs/guide/http/fluentvalidation.md | 27 ++++++++++++++++++++++-
 docs/guide/http/middleware.md       | 33 ++++++++++++++++++++++++++++-
 docs/guide/http/problemdetails.md   | 29 ++++++++++++++++++++++++-
 3 files changed, 86 insertions(+), 3 deletions(-)

diff --git a/docs/guide/http/fluentvalidation.md b/docs/guide/http/fluentvalidation.md
index 08a3b4191..987137035 100644
--- a/docs/guide/http/fluentvalidation.md
+++ b/docs/guide/http/fluentvalidation.md
@@ -22,4 +22,29 @@ opts.UseFluentValidationProblemDetailMiddleware();
 
 as shown in context below in an application shown below:
 
-snippet: sample_using_configure_endpoints
+<!-- snippet: sample_using_configure_endpoints -->
+<a id='snippet-sample_using_configure_endpoints'></a>
+```cs
+app.MapWolverineEndpoints(opts =>
+{
+    // This is strictly to test the endpoint policy
+    
+    
+    opts.ConfigureEndpoints(httpChain =>
+    {
+        // The HttpChain model is a configuration time
+        // model of how the HTTP endpoint handles requests
+
+        // This adds metadata for OpenAPI
+        httpChain.WithMetadata(new CustomMetadata());
+        httpChain.WithTags("wolverine");
+    });
+    
+    // more configuration for HTTP...
+    
+    // Opting into the Fluent Validation middleware from
+    // Wolverine.Http.FluentValidation
+    opts.UseFluentValidationProblemDetailMiddleware();
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Program.cs#L80-L103' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_using_configure_endpoints' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
diff --git a/docs/guide/http/middleware.md b/docs/guide/http/middleware.md
index 495ee8d09..165a8ba33 100644
--- a/docs/guide/http/middleware.md
+++ b/docs/guide/http/middleware.md
@@ -197,7 +197,38 @@ continue working against that entity data you just loaded. To help remove boiler
 support for this pattern using the standard `[Required]` attribute on the parameters of the inputs to the HTTP handler
 methods. Here's an example that tries to apply an update to an existing `Todo` entity:
 
-snippet: sample_update_with_required_entity
+<!-- snippet: sample_update_with_required_entity -->
+<a id='snippet-sample_update_with_required_entity'></a>
+```cs
+public record UpdateRequest(string Name, bool IsComplete);
+
+public static class UpdateEndpoint
+{
+    // Find required Todo entity for the route handler below
+    public static Task<Todo?> LoadAsync(int id, IDocumentSession session) 
+        => session.LoadAsync<Todo>(id);
+    
+    [WolverinePut("/todos/{id:int}")]
+    public static StoreDoc<Todo> Put(
+        // Route argument
+        int id,
+        
+        // The request body
+        UpdateRequest request,
+        
+        // Entity loaded by the method above, 
+        // but note the [Required] attribute
+        [Required] Todo? todo)
+    {
+        todo.Name = request.Name;
+        todo.IsComplete = request.IsComplete;
+
+        return MartenOps.Store(todo);
+    }
+}
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/WolverineWebApi/Samples/TodoController.cs#L123-L152' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_update_with_required_entity' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
 
 You'll notice that the `LoadAsync()` method is looking up the `Todo` entity for the route parameter, where Wolverine would
 normally be passing that value to the matching `Todo` parameter of the main `Put` method. In this case though, because of 
diff --git a/docs/guide/http/problemdetails.md b/docs/guide/http/problemdetails.md
index 2fb9f8803..d47af7a87 100644
--- a/docs/guide/http/problemdetails.md
+++ b/docs/guide/http/problemdetails.md
@@ -78,7 +78,34 @@ To make that clearer, here's the generated code:
 
 And for more context, here's the matching "happy path" and "sad path" tests for the endpoint above:
 
-sample: sample_testing_problem_details_behavior
+<!-- snippet: sample_testing_problem_details_behavior -->
+<a id='snippet-sample_testing_problem_details_behavior'></a>
+```cs
+[Fact]
+public async Task continue_happy_path()
+{
+    // Should be good
+    await Scenario(x =>
+    {
+        x.Post.Json(new NumberMessage(3)).ToUrl("/problems");
+    });
+}
+
+[Fact]
+public async Task stop_with_problems_if_middleware_trips_off()
+{
+    // This is the "sad path" that should spawn a ProblemDetails
+    // object
+    var result = await Scenario(x =>
+    {
+        x.Post.Json(new NumberMessage(10)).ToUrl("/problems");
+        x.StatusCodeShouldBe(400);
+        x.ContentTypeShouldBe("application/problem+json");
+    });
+}
+```
+<sup><a href='https://github.com/JasperFx/wolverine/blob/main/src/Http/Wolverine.Http.Tests/problem_details_usage_in_http_middleware.cs#L18-L43' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_testing_problem_details_behavior' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
 
 Lastly, if Wolverine sees the existence of a `ProblemDetails` return value in any middleware, Wolverine will fill in OpenAPI
 metadata for the "application/problem+json" content type and a status code of 400. This behavior can be easily overridden