Update README.md

Author: jkone27

README.md

@@ -1,22 +1,41 @@
-[![Ceasefire Now](https://badge.techforpalestine.org/ceasefire-now)](https://techforpalestine.org/learn-more)
-[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua)
-<a href='https://juststopoil.org/' target="_blank"><img alt='JUST_STOP_OIL' src='https://img.shields.io/badge/Just_STOP OIL-100000?style=plastic&logo=JUST_STOP_OIL&logoColor=white&labelColor=FFA600&color=000000'/></a>
+# ApiStub.FSharp [![NuGet Badge](https://img.shields.io/nuget/v/ApiStub.FSharp)](https://www.nuget.org/packages/ApiStub.FSharp) 🦔
 
+<img width="331" alt="Screenshot 2024-12-16 at 13 01 33" src="https://github.com/user-attachments/assets/5095d6cb-63bb-4644-836f-99b5355870fe" />
 
-# ApiStub.FSharp [![NuGet Badge](https://img.shields.io/nuget/v/ApiStub.FSharp)](https://www.nuget.org/packages/ApiStub.FSharp)
 
-You have an ASP NET NET6+ (NET6 is LTS in 2023) dotnet API, and you want to simplify HTTP stubs for integration
-testing, so you can make use of these Computation Expressions (CE) to simplify
-your tests with some integration testing HTTP stubs DSL. 
+[![Ceasefire Now](https://badge.techforpalestine.org/ceasefire-now)](https://techforpalestine.org/learn-more)  
+[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua)  
+<a href='https://juststopoil.org/' target="_blank"><img alt='JUST_STOP_OIL' src='https://img.shields.io/badge/Just_STOP OIL-100000?style=plastic&logo=JUST_STOP_OIL&logoColor=white&labelColor=FFA600&color=000000'/></a>  
 
-To use the CE, you must build your CE object first by passing the generic Startup type argument. 
-For how the library is implemented, it still needs you to provide a Startup class, 
-future versions might make use of Program only from minimal API (this already uses WebApplication only anyway).
+# Easy API Testing 🧞‍♀️
+
+You have an ASP NET NET6+ (NET6 is LTS in 2023) aspnetcore API, and you want to simplify HTTP stubs for [integration
+testing](https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests?view=aspnetcore-9.0) using `WebApplicationFactory`, 
+but you find that a bit cumbersome sometimes? 
+
+this library is here to help you!
+
+## Mechanics
+
+This library makes use of [F# computation expressions](https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/computation-expressions) to hide some complexity of `WebApplicationFactory` and provide the user with a *domain specific language* (DSL) for integration tests in aspnetcore apps.
+The best way to understand how it all works is checking the [code](https://github.com/jkone27/fsharp-integration-tests/blob/249c3244cd7e20e2168b82a49b6e7e14f2ad1004/ApiStub.FSharp/CE.fs#L176) and this member CE method `GetFactory()` in scope.
+
+If you have ideas for improvements feel free to open an issue/discussion! 
+I do this on my own time, so support is limited but contributions/PRs are welcome 🙏 
 
-**How** does the library work? the best way to understand it is checking this line of [code](https://github.com/jkone27/fsharp-integration-tests/blob/249c3244cd7e20e2168b82a49b6e7e14f2ad1004/ApiStub.FSharp/CE.fs#L176) and the member CE method `GetFactory()` in scope.
+## Features 👨🏻‍🔬
 
+* **HTTP client mock DSL**:
+    * supports main HTTP verbs
+    * support for JSON payload for automatic object serialization
+* **BDD spec dsl extension** (behaviour driven development)
+    * to express tests in gherkin GIVEN, WHEN, THEN format if you want to
+* EXTRAS
+    * utilities for test setup and more...
 
-## USAGE
+## Usage
+
+To use the CE, you must build your CE object first by passing the generic Startup type argument. 
 
 Suppose your server registers 2 API clients internally to make calls to other services, say to the outbound routes `externalApi` and `anotherApi`,
 one client using `GET` and another using `POST` methods inside your API client code. 
@@ -53,9 +72,11 @@ module Tests =
         } 
 ```
 
-## HTTP MOCKING METHODS
+## HTTP Methods 🚕
+
+Available HTTP methods in the test dsl to "mock" HTTP client responses are the following:
 
-Available HTTP mocking methods in the test dsl are: 
+### Basic
 
 * `GET`, `PUT`, `POST`, `DELETE` - for accessing request, route parameters and sending back HttpResponseMessage (e.g. using R_JSON or other constructors)
 
@@ -68,12 +89,16 @@ Available HTTP mocking methods in the test dsl are:
     )
 ```
 
+### JSON
+
 * `GETJ`, `PUTJ`, `POSTJ`, `DELETEJ` - for objects converted to JSON content
 
 ```fsharp
 GETJ "/yetAnotherOne" {| Success = true |}
 ```
 
+### Async (task)
+
 * `GET_ASYNC`, `PUT_ASYNC`, `POST_ASYNC`, `DELETE_ASYNC` - for handling asynchronous requests inside a task computation expression (async/await) and mock dynamically
 
 ```fsharp
@@ -87,20 +112,20 @@ GETJ "/yetAnotherOne" {| Success = true |}
     )
 ```
 
-## HTTP RESPONSE CONSTRUCTORS
+### Http response helpers 👨🏽‍🔧
 
 Available HTTP content constructors are: 
 
 * `R_TEXT`: returns plain text
 * `R_JSON`: returns JSON
 * `R_ERROR`: returns an HTTP error
 
-## Configure Services HELPERS
+## Configure Services Helpers 🪈
 
 * `WITH_SERVICES`: to override your ConfigureServices for tests
 * `WITH_TEST_SERVICES`: to override your specific test services (a bit redundant in some cases, depending on the need)
 
-## BDD Extensions
+## BDD (gherkin) Extensions 🥒
 
 You can use some BDD extension to perform [Gherkin-like setups and assertions](https://cucumber.io/docs/gherkin/reference/)
 
@@ -175,12 +200,13 @@ module BDDTests =
 
 Please take a look at the examples in the `test` folder for more details on the usage.
 
-## ApiStub.FSharp.Stubbery
+## ApiStub.FSharp.Stubbery ⚠️ 🐦
 
 A version using the [Stubbery](https://github.com/markvincze/Stubbery) library is also present for "compatibility" when migrating from `stubbery` versions of pre existing integration tests, in your integration tests setup.
 
 In general, it's advised to not have dependencies or run any in-memory HTTP server if possible, so the minimal version is preferred.
 
+NOTICE ⚠️: Stubbery will not be supported in adding new features or eventually might be not supported at all in the future.
 
 ```fsharp
 open ApiStub.FSharp.Stubbery.StubberyCE
@@ -213,7 +239,7 @@ module Tests =
 ```
 
 
-## How to Contribute
+## How to Contribute ✍️
 
 * Search for an open issue or report one, and check if a similar issue was reported first
 * feel free to get in touch, to fork and check out the repo