Dev (#26)

* - Removed try block to catch and wrap exception in a Result object in DefaultServiceChannel SendAsync methods. Leave it to caller to handle exceptions.

* - simplify empty interface definitions

* - add Open API documentation information to docs

* - change path of OpenApiDocumentation.md

* - add WebResultEndpoint Response Mapping doc

* - update individual readme.md asset files for each package

* - seperate documentation for service endpoint clients

* - bump version

Author: modabas

Directory.Build.props

@@ -18,6 +18,6 @@
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageRequireLicenseAcceptance>True</PackageRequireLicenseAcceptance>
 
-    <Version>1.1.0</Version>
+    <Version>1.1.1</Version>
   </PropertyGroup>
 </Project>

ModEndpoints.sln

@@ -52,8 +52,12 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{9FD33E1B-1
 		docs\EndpointTypes.md = docs\EndpointTypes.md
 		docs\HandlingFiles.md = docs\HandlingFiles.md
 		docs\IAsyncEnumerableResponse.md = docs\IAsyncEnumerableResponse.md
+		docs\OpenApiDocumentation.md = docs\OpenApiDocumentation.md
 		docs\ParameterBinding.md = docs\ParameterBinding.md
+		docs\ResultPatternIntegration.md = docs\ResultPatternIntegration.md
 		docs\RouteGroups.md = docs\RouteGroups.md
+		docs\ServiceEndpointClients.md = docs\ServiceEndpointClients.md
+		docs\WebResultEndpointResponseMapping.md = docs\WebResultEndpointResponseMapping.md
 	EndProjectSection
 EndProject
 Global

README.md

@@ -232,11 +232,14 @@ For more examples, refer to the following:
 
 - [Parameter Binding](./docs/ParameterBinding.md)  
 - [Route Groups](./docs/RouteGroups.md)
-- [IAsyncEnumerable Response](./docs/IAsyncEnumerableResponse.md)
-- [Handling Files](./docs/HandlingFiles.md)
 - [Disabling Components](./docs/DisablingComponents.md)
-- [Result Pattern Integration](./docs/ResultPatternIntegration.md)
+- [Open API Documentation](./docs/OpenApiDocumentation.md)
+- [Handling Files](./docs/HandlingFiles.md)
 - [Endpoint Types](./docs/EndpointTypes.md)
+- [Result Pattern Integration](./docs/ResultPatternIntegration.md)
+- [IAsyncEnumerable Response](./docs/IAsyncEnumerableResponse.md)
+- [WebResultEndpoint Response Mapping](./docs/WebResultEndpointResponseMapping.md)
+- [ServiceEndpoint Clients](./docs/ServiceEndpointClients.md)
 
 ---
 

docs/EndpointTypes.md

@@ -78,56 +78,4 @@ A ServiceEndpoint has following special traits and constraints:
 - A ServiceEndpoint's request is specific to that endpoint. Each endpoint must have its unique request type.
 - To utilize the advantages of a ServiceEndpoint over other endpoint types, its request and response models have to be shared with clients and therefore has to be in a seperate class library.
 
-These restrictions enable clients to call ServiceEndpoints by utilizing a specialized message channel resolved from dependency injection, with only service base address and endpoint's request/response model information. No other client implementation or knowledge about service is required.
-
-Have a look at [sample ServiceEndpoint implementations](../samples/ShowcaseWebApi/Features/StoresWithServiceEndpoint) along with [sample client implementation](../samples/Client) and [request/response model shared library](../samples/ShowcaseWebApi.FeatureContracts).
-
-## ServiceEndpoint clients
-
-A client application consuming ServiceEndpoints, creates service channel registry entries for those endpoints (remote services) during application startup, basically mapping which request message type will be sent by using which HttpClient configuration (base address, timeout, handlers, resilience definitions, etc.). Service channel utilizes IHttpClientFactory and HttpClient underneath and is configured similarly.
-
-Registration can be done either for all service requests in an assembly...
-```csharp
-var baseAddress = "https://...";
-var clientName = "MyClient";
-builder.Services.AddRemoteServicesWithNewClient(
-  typeof(ListStoresRequest).Assembly,
-  clientName,
-  (sp, client) =>
-  {
-    client.BaseAddress = new Uri(baseAddress);
-    client.Timeout = TimeSpan.FromSeconds(5);
-  },
-  clientBuilder => clientBuilder.AddTransientHttpErrorPolicy(
-    policyBuilder => policyBuilder.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30))));
-```
-
-or alternatively, remote services can be registered one by one, adding each service request individually...
-```csharp
-var baseAddress = "https://...";
-var clientName = "MyClient";
-builder.Services.AddRemoteServiceWithNewClient<ListStoresRequest>(clientName,
-  (sp, client) =>
-  {
-    client.BaseAddress = new Uri(baseAddress);
-    client.Timeout = TimeSpan.FromSeconds(5);
-  },
-  clientBuilder => clientBuilder.AddTransientHttpErrorPolicy(
-    policyBuilder => policyBuilder.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30))));
-builder.Services.AddRemoteServiceToExistingClient<GetStoreByIdRequest>(clientName);
-builder.Services.AddRemoteServiceToExistingClient<DeleteStoreRequest>(clientName);
-builder.Services.AddRemoteServiceToExistingClient<CreateStoreRequest>(clientName);
-builder.Services.AddRemoteServiceToExistingClient<UpdateStoreRequest>(clientName);
-```
-
-Then remote services are called with IServiceChannel instance resolved from DI...
-```csharp
-  using IServiceScope serviceScope = hostProvider.CreateScope();
-  IServiceProvider provider = serviceScope.ServiceProvider;
-
-  //resolve service channel from DI
-  var channel = provider.GetRequiredService<IServiceChannel>();
-  //send request over channel to remote service
-  var listResult = await channel.SendAsync(new ListStoresRequest(), ct);
-
-```
+These restrictions enable clients to call ServiceEndpoints by utilizing a specialized message channel resolved from dependency injection, see [ServiceEndpoint Clients](ServiceEndpointClients.md) documentation for details.

docs/OpenApiDocumentation.md

@@ -0,0 +1,7 @@
+# Open API Documentation
+
+API documentation follows the same approach as .NET Core Minimal APIs. You only need to use your preferred documentation generator; no additional packages are required.
+
+[ShowcaseWebApi](./samples/ShowcaseWebApi) sample project uses `Swashbuckle.AspNetCore`.
+
+[WeatherForecastWebApi](./samples/WeatherForecastWebApi) sample project uses `Microsoft.AspNetCore.OpenApi` and `Scalar.AspNetCore`. 

docs/ServiceEndpointClients.md

@@ -0,0 +1,71 @@
+# ServiceEndpoint Clients
+
+A client application can consume ServiceEndpoints by utilizing a specialized message channel resolved from dependency injection. Only service's base address and endpoint's request/response model information are needed. No other client implementation or service specific knowledge is required.
+
+## ⚙️ Workflow
+
+The workflow for consuming ServiceEndpoints from a client application consists of two main steps: **registration** and **consumption**. 
+
+### Registration
+
+A client application registers service endpoints with a specific HttpClient configuration (such as base address, timeout, handlers, resilience policies, etc.) during application startup. This can be performed for all service requests within an assembly or for each request type individually.
+
+To register all service requests in an assembly at once:
+
+```csharp
+var baseAddress = "https://...";
+var clientName = "MyClient";
+builder.Services.AddRemoteServicesWithNewClient(
+  typeof(ListStoresRequest).Assembly,
+  clientName,
+  (sp, client) =>
+  {
+    client.BaseAddress = new Uri(baseAddress);
+    client.Timeout = TimeSpan.FromSeconds(5);
+  },
+  clientBuilder => clientBuilder.AddTransientHttpErrorPolicy(
+    policyBuilder => policyBuilder.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30))));
+```
+
+...or to register service requests individually:
+
+```csharp
+var baseAddress = "https://...";
+var clientName = "MyClient";
+builder.Services.AddRemoteServiceWithNewClient<ListStoresRequest>(clientName,
+  (sp, client) =>
+  {
+    client.BaseAddress = new Uri(baseAddress);
+    client.Timeout = TimeSpan.FromSeconds(5);
+  },
+  clientBuilder => clientBuilder.AddTransientHttpErrorPolicy(
+    policyBuilder => policyBuilder.CircuitBreakerAsync(5, TimeSpan.FromSeconds(30))));
+builder.Services.AddRemoteServiceToExistingClient<GetStoreByIdRequest>(clientName);
+builder.Services.AddRemoteServiceToExistingClient<DeleteStoreRequest>(clientName);
+builder.Services.AddRemoteServiceToExistingClient<CreateStoreRequest>(clientName);
+builder.Services.AddRemoteServiceToExistingClient<UpdateStoreRequest>(clientName);
+```
+>**Notes**:
+>1. The client name is used to resolve the correct HttpClient configuration for each request type.
+>2. Service channel utilizes IHttpClientFactory and HttpClient underneath and is configured similarly.
+
+### Comsumption
+
+Remote `ServiceEndpoints` can be called by resolving an `IServiceChannel` instance from dependency injection and invoking the `SendAsync` method with the desired request object.
+
+```csharp
+  using IServiceScope serviceScope = hostProvider.CreateScope();
+  IServiceProvider provider = serviceScope.ServiceProvider;
+
+  //resolve service channel from DI
+  var channel = provider.GetRequiredService<IServiceChannel>();
+  //send request over channel to remote service
+  var listResult = await channel.SendAsync(new ListStoresRequest(), ct);
+
+```
+
+## 📚 Samples
+1. [ServiceEndpoint implementations](../samples/ShowcaseWebApi/Features/StoresWithServiceEndpoint)
+2. [Client implementation](../samples/ServiceEndpointClient)
+3. [Shared library for request/response models](../samples/ShowcaseWebApi.FeatureContracts).
+

docs/WebResultEndpointResponseMapping.md

@@ -0,0 +1,91 @@
+# WebResultEndpoint Response Mapping
+
+`WebResultEndpoint` transforms the result returned by its `HandleAsync` method —a business result— into appropriate HTTP status code and response format, providing consistent and type-safe API behavior. This process relies on a default result-to-response mapper.
+
+There are several ways to customize how responses are mapped:
+
+One way to customize response mapping is by overriding the ConvertResultToResponseAsync method. This method is invoked after HandleAsync to transform the business result into an HTTP response. By default, it uses the IResultToResponseMapper service for this conversion, but you can override it to implement your own mapping logic.
+
+``` csharp
+internal class GetBookById(ServiceDbContext db)
+  : WebResultEndpoint<GetBookByIdRequest, GetBookByIdResponse>
+{
+  protected override void Configure(
+    IServiceProvider serviceProvider,
+    IRouteGroupConfigurator? parentRouteGroup)
+  {
+    MapGet("/{Id}")
+      .Produces<GetBookByIdResponse>();
+  }
+
+  protected override ValueTask<IResult> ConvertResultToResponseAsync(
+    Result<GetBookByIdResponse> result,
+    HttpContext context,
+    CancellationToken ct)
+  {
+    // Custom mapping logic here
+
+  }
+
+  protected override async Task<Result<GetBookByIdResponse>> HandleAsync(
+    GetBookByIdRequest req,
+    CancellationToken ct)
+  {
+    // implementation
+
+  }
+}
+```
+
+Another option is to implement your own `IResultToResponseMapper` and register it in the DI container as a keyed service using a string key.
+You can then apply the `[ResultToResponseMapper("MyMapperKey")]` attribute to any `WebResultEndpoint`-based endpoint to have it use your custom mapper instead of the default one.
+
+``` csharp
+// Lifetime of the mapper is defined as singleton only for example purposes, it can be any lifetime
+services.TryAddKeyedSingleton<IResultToResponseMapper, MyResultToResponseMapper>("MyMapper");
+```
+
+``` csharp
+[ResultToResponseMapper("MyMapper")]
+internal class GetBookById
+  : WebResultEndpoint<GetBookByIdRequest, GetBookByIdResponse>
+{
+  protected override void Configure(
+    IServiceProvider serviceProvider,
+    IRouteGroupConfigurator? parentRouteGroup)
+  {
+    MapGet("/{Id}")
+      .Produces<GetBookByIdResponse>();
+  }
+
+  protected override async Task<Result<GetBookByIdResponse>> HandleAsync(
+    GetBookByIdRequest req,
+    CancellationToken ct)
+  {
+    // implementation
+
+  }
+}
+```
+
+It is also possible to replace default mapper for all endpoints by registering your mapper as the default mapper before invoking any variant of `AddModEndpoints` method.
+
+``` csharp
+var builder = WebApplication.CreateBuilder(args);
+
+
+// Register your custom mapper as the default mapper
+// Lifetime of the mapper is defined as singleton only for example purposes, it can be any lifetime
+services.TryAddKeyedSingleton<IResultToResponseMapper, MyResultToResponseMapper>(
+  WebResultEndpointDefinitions.DefaultResultToResponseMapperName);
+
+builder.Services.AddModEndpointsFromAssemblyContaining<MyEndpoint>();
+//Validation
+builder.Services.AddValidatorsFromAssemblyContaining<MyValidator>(includeInternalTypes: true);
+
+var app = builder.Build();
+
+app.MapModEndpoints();
+
+app.Run();
+```

src/ModEndpoints.Core/[Endpoints]/IBusinessResultEndpoint.cs

@@ -1,5 +1,3 @@
 namespace ModEndpoints.Core;
 
-public interface IBusinessResultEndpoint
-{
-}
+public interface IBusinessResultEndpoint;

src/ModEndpoints.Core/[Endpoints]/IMinimalEndpoint.cs

@@ -1,5 +1,3 @@
 namespace ModEndpoints.Core;
 
-public interface IMinimalEndpoint
-{
-}
+public interface IMinimalEndpoint;

src/ModEndpoints.Core/[Endpoints]/IServiceEndpoint.cs

@@ -1,5 +1,3 @@
 namespace ModEndpoints.Core;
 
-public interface IServiceEndpoint
-{
-}
+public interface IServiceEndpoint;