Merge pull request #13 from sheepla/devin/1777641381-docs-simplification

docs: simplify README and create Astro Starlight documentation pages

Author: sheepla

README.md

@@ -18,7 +18,37 @@ export default defineConfig({
         },
       ],
       sidebar: [
-        //
+        {
+          label: "Getting Started",
+          items: [
+            { label: "Installation", slug: "getting-started/installation" },
+            { label: "Quick Start", slug: "getting-started/quick-start" },
+          ],
+        },
+        {
+          label: "Guides",
+          items: [
+            { label: "Defining Endpoints", slug: "guides/defining-endpoints" },
+            { label: "Request Binding", slug: "guides/request-binding" },
+            { label: "Response Types", slug: "guides/response-types" },
+            { label: "Validation", slug: "guides/validation" },
+            { label: "Authorization", slug: "guides/authorization" },
+            { label: "Error Responses", slug: "guides/error-responses" },
+            { label: "Endpoint Groups", slug: "guides/endpoint-groups" },
+            { label: "Filters", slug: "guides/filters" },
+            { label: "HTTP Context", slug: "guides/http-context" },
+          ],
+        },
+        {
+          label: "Extensions",
+          items: [
+            { label: "CSV Helper", slug: "extensions/csv-helper" },
+            { label: "CSV Import", slug: "extensions/csv-helper/csv-import" },
+            { label: "CSV Export", slug: "extensions/csv-helper/csv-export" },
+            { label: "Row Validation", slug: "extensions/csv-helper/row-validation" },
+            { label: "Class Map", slug: "extensions/csv-helper/class-map" },
+          ],
+        },
       ],
     }),
     react(),

docs/astro.config.mjs

@@ -0,0 +1,37 @@
+---
+title: "Class Map"
+description: "Customize CSV column-to-property mapping using CsvHelper ClassMap."
+---
+
+Override `CreateClassMap()` on the derived request type to supply a CsvHelper `ClassMap` instead of relying on attributes:
+
+## Import
+
+```csharp
+public sealed class ImportUsersRequest : CsvRequest<UserImportRow>
+{
+    public static ValueTask<ImportUsersRequest> BindAsync(HttpContext context)
+        => BindCsvAsync<ImportUsersRequest>(context);
+
+    protected override ClassMap CreateClassMap() => new UserImportRowMap();
+}
+
+public sealed class UserImportRowMap : ClassMap<UserImportRow>
+{
+    public UserImportRowMap()
+    {
+        Map(r => r.Name).Name("full_name");
+        Map(r => r.Email).Name("email_address");
+    }
+}
+```
+
+## Export
+
+The same `CreateClassMap()` override is available on `CsvResponse<TRow>` via the `classMap` parameter of `CsvResponse.From`:
+
+```csharp
+CsvResponse.From(rows, classMap: new UserExportRowMap(), fileName: "users.csv")
+```
+
+For the full CSV import example, see [CSV Import](/extensions/csv-helper/csv-import/). For export, see [CSV Export](/extensions/csv-helper/csv-export/).

docs/src/content/docs/extensions/csv-helper/class-map.mdx

@@ -0,0 +1,38 @@
+---
+title: "CSV Export"
+description: "Stream typed rows as a CSV download using CsvResponse<TRow>."
+---
+
+Return `CsvResponse<TRow>` directly from `HandleAsync`. It implements `IResult`, so the framework streams the rows to the response without buffering the entire dataset in memory.
+
+```csharp
+public sealed class UserExportRow
+{
+    [Name("id")]    public int    Id    { get; init; }
+    [Name("name")]  public string Name  { get; init; } = string.Empty;
+    [Name("email")] public string Email { get; init; } = string.Empty;
+}
+
+public sealed class ExportUsersEndpoint : IEndpoint<CsvResponse<UserExportRow>>
+{
+    private readonly IUserRepository _repository;
+
+    public ExportUsersEndpoint(IUserRepository repository) => _repository = repository;
+
+    public void Configure(IEndpointConfiguration config)
+    {
+        config.Get("/users/export").Summary("Export users as CSV");
+    }
+
+    public Task<CsvResponse<UserExportRow>> HandleAsync(CancellationToken cancel)
+    {
+        // IAsyncEnumerable<T> is written row-by-row without loading everything into memory.
+        var rows = _repository.GetAllAsync(cancel);
+        return Task.FromResult(CsvResponse.From(rows, fileName: "users.csv"));
+    }
+}
+```
+
+`CsvResponse.From` also accepts `IEnumerable<T>` for synchronous sequences.
+
+For custom column mapping on export, see [Class Map](/extensions/csv-helper/class-map/).

docs/src/content/docs/extensions/csv-helper/csv-export.mdx

@@ -0,0 +1,45 @@
+---
+title: "CSV Import"
+description: "Import CSV data into typed rows using CsvRequest<TRow>."
+---
+
+Derive your request type from `CsvRequest<TRow>`. After binding, `request.Rows` contains the parsed rows as `IReadOnlyList<TRow>`.
+
+Minimal API requires `BindAsync` to be declared as a non-generic static method on the concrete type, so it cannot be provided by the base class. Declare it in the derived class and delegate to `BindCsvAsync<T>`:
+
+```csharp
+public sealed class UserImportRow
+{
+    [Name("name")]  public string Name  { get; init; } = string.Empty;
+    [Name("email")] public string Email { get; init; } = string.Empty;
+    [Name("role")]  public string Role  { get; init; } = string.Empty;
+}
+
+public sealed class ImportUsersRequest : CsvRequest<UserImportRow>
+{
+    public static ValueTask<ImportUsersRequest> BindAsync(HttpContext context)
+        => BindCsvAsync<ImportUsersRequest>(context);
+}
+
+public sealed class ImportUsersEndpoint : IEndpoint<ImportUsersRequest, Response<EmptyResponse>>
+{
+    public void Configure(IEndpointConfiguration config)
+    {
+        config.Post("/users/import")
+            .AddFilter<CsvBindingExceptionFilter>()
+            .Summary("Import users from CSV");
+    }
+
+    public Task<Response<EmptyResponse>> HandleAsync(
+        ImportUsersRequest request,
+        CancellationToken cancel)
+    {
+        foreach (var row in request.Rows) { /* persist row */ }
+        return Task.FromResult(Response.NoContent);
+    }
+}
+```
+
+Both `text/csv` direct body and `multipart/form-data` file uploads are supported automatically.
+
+For per-row validation, see [Row Validation](/extensions/csv-helper/row-validation/). For custom column mapping, see [Class Map](/extensions/csv-helper/class-map/).

docs/src/content/docs/extensions/csv-helper/csv-import.mdx

@@ -0,0 +1,31 @@
+---
+title: "CSV Helper"
+description: "Add typed CSV import and export to your AxisEndpoints with the CsvHelper extension package."
+---
+
+The `AxisEndpoints.Extensions.CsvHelper` package adds typed CSV import and export to AxisEndpoints endpoints, backed by [CsvHelper](https://joshclose.github.io/CsvHelper/).
+
+## Installation
+
+```sh
+dotnet add package AxisEndpoints.Extensions.CsvHelper
+```
+
+## Setup
+
+Register the extension services in `Program.cs`:
+
+```csharp
+using AxisEndpoints.Extensions;
+using AxisEndpoints.Extensions.CsvHelper;
+
+builder.Services.AddAxisEndpoints();
+builder.Services.AddAxisEndpointsCsvHelper(); // registers CsvBindingExceptionFilter
+```
+
+## Next steps
+
+- [CSV Import](/extensions/csv-helper/csv-import/) — parse incoming CSV data into typed rows
+- [CSV Export](/extensions/csv-helper/csv-export/) — stream typed rows as a CSV download
+- [Row Validation](/extensions/csv-helper/row-validation/) — validate each row with DataAnnotations
+- [Class Map](/extensions/csv-helper/class-map/) — customize column-to-property mapping

docs/src/content/docs/extensions/csv-helper/index.mdx

@@ -0,0 +1,28 @@
+---
+title: "Row Validation"
+description: "Validate CSV rows with DataAnnotations and surface errors as structured responses."
+---
+
+DataAnnotations attributes on `TRow` are validated during binding, one row at a time. All errors are collected before the handler is invoked and surfaced as an RFC 9457 `ValidationProblem` response by `CsvBindingExceptionFilter`.
+
+Error keys follow the pattern `"row {n}: {MemberName}"`:
+
+```json
+{
+  "status": 400,
+  "errors": {
+    "row 3: Email": ["The Email field is not a valid e-mail address."],
+    "row 5: Name":  ["The Name field is required."]
+  }
+}
+```
+
+## Registering the filter
+
+Register `CsvBindingExceptionFilter` on any endpoint that accepts a `CsvRequest<TRow>` parameter:
+
+```csharp
+config.Post("/users/import").AddFilter<CsvBindingExceptionFilter>();
+```
+
+For general DataAnnotations validation on request types, see the [Validation](/guides/validation/) guide.

docs/src/content/docs/extensions/csv-helper/row-validation.mdx

@@ -0,0 +1,32 @@
+---
+title: "Installation"
+description: "Install AxisEndpoints and optional extension packages in your ASP.NET Core project."
+---
+
+## Install from nuget.org
+
+Add the core package to your project:
+
+```sh
+dotnet add package AxisEndpoints
+```
+
+For the CSV extension:
+
+```sh
+dotnet add package AxisEndpoints.Extensions.CsvHelper
+```
+
+## Install from local nupkg
+
+If you are building from source or testing a pre-release version, you can install from a local `.nupkg` file:
+
+```sh
+# Build the NuGet package
+dotnet pack src/AxisEndpoints/AxisEndpoints.csproj -o <LocalNupkgDirectory>
+
+# Add it to your project
+dotnet add <YourProject> package AxisEndpoints --source <LocalNupkgDirectory>
+```
+
+Once installed, proceed to the [Quick Start](/getting-started/quick-start/) guide to set up your first endpoint.

docs/src/content/docs/getting-started/installation.mdx

@@ -0,0 +1,71 @@
+---
+title: "Quick Start"
+description: "Set up AxisEndpoints in your ASP.NET Core project and create your first endpoint."
+---
+
+## Setup in Program.cs
+
+Call `AddAxisEndpoints()` on the service collection and `MapAxisEndpoints()` on the application. Both methods scan the entry assembly automatically. Pass an `Assembly` argument to target a specific project.
+
+```csharp
+using AxisEndpoints.Extensions;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddOpenApi();
+builder.Services.AddAxisEndpoints(); // Discovers and registers all endpoints
+
+var app = builder.Build();
+
+app.MapOpenApi();
+app.MapAxisEndpoints(); // Maps all discovered endpoints to the Minimal API pipeline
+
+app.Run();
+```
+
+## Your first endpoint
+
+Here is a complete example of a POST endpoint that creates a user and returns a JSON response:
+
+```csharp
+public class CreateUserRequest
+{
+    public required string Name { get; init; }
+    public required string Email { get; init; }
+}
+
+public class CreateUserResponse
+{
+    public required int Id { get; init; }
+}
+
+public class CreateUserEndpoint : IEndpoint<CreateUserRequest, Response<CreateUserResponse>>
+{
+    private readonly IUserRepository _repository;
+
+    public CreateUserEndpoint(IUserRepository repository) => _repository = repository;
+
+    public void Configure(IEndpointConfiguration config)
+    {
+        config.Post("/users")
+            .Tags("Users")
+            .Summary("Create a new user");
+    }
+
+    public async Task<Response<CreateUserResponse>> HandleAsync(
+        CreateUserRequest request,
+        CancellationToken cancel)
+    {
+        var id = await _repository.CreateAsync(request.Name, request.Email, cancel);
+
+        return new Response<CreateUserResponse>
+        {
+            StatusCode = HttpStatusCode.Created,
+            Headers    = [("Location", $"/users/{id}")],
+            Body       = new CreateUserResponse { Id = id },
+        };
+    }
+}
+```
+
+For more details on defining endpoints, see the [Defining Endpoints](/guides/defining-endpoints/) guide.