Added documentation for "Serializers"

Author: bastianeicher

docs/serializers/.pages

@@ -0,0 +1,5 @@
+nav:
+  - index.md
+  - json.md
+  - bson.md
+  - xml.md

docs/serializers/bson.md

@@ -0,0 +1,27 @@
+# BSON
+
+BSON (Binary JSON) serialization is available in the .NET implementation of TypedRest.
+
+=== "C#"
+
+    The BSON serializer provides efficient binary serialization using Newtonsoft.Json's BSON support:
+
+    ```csharp
+    using TypedRest.Serializers;
+
+    var serializer = new BsonSerializer();
+    var endpoint = new EntryEndpoint(
+        new Uri("http://example.com/"),
+        serializer: serializer);
+    ```
+
+    The BSON serializer uses the same Newtonsoft.Json settings as the default JSON serializer:
+
+    - Camel-case property naming
+    - String enums with camel-case naming
+    - Null values are not serialized
+    - Automatic type name handling
+
+## Content type
+
+TODO: The serializer handles the `application/bson` content type.

docs/serializers/index.md

@@ -1,3 +1,37 @@
 # Serializers
 
 Serializers control how entities are serialized when sending requests and deserialized when receiving responses.
+
+TypedRest provides built-in serializers for various transport formats:
+
+- [JSON](json.md)
+- [BSON](bson.md)
+- [XML](xml.md)
+
+You can also create and use custom serializers.
+
+## Inheritance
+
+When creating [endpoints](../endpoints/index.md), the serializer is automatically inherited from the parent (referrer) endpoint:
+
+=== "C#"
+
+    ```csharp
+    var client = new EntryEndpoint(new Uri("http://example.com/"));
+    client.Serializer = new SystemTextJsonSerializer();
+
+    var contacts = new CollectionEndpoint<Contact>(client, relativeUri: "./contacts");
+    // contacts.Serializer is automatically set to the same SystemTextJsonSerializer
+    ```
+
+=== "TypeScript"
+
+    ```typescript
+    const client = new EntryEndpoint(new URL("http://example.com/"));
+    client.serializer = new CustomSerializer();
+
+    const contacts = new CollectionEndpoint<Contact>(client, "./contacts");
+    // contacts.serializer is automatically set to the same CustomSerializer
+    ```
+
+This inheritance ensures consistent serialization behavior across your entire endpoint hierarchy.

docs/serializers/json.md

@@ -0,0 +1,104 @@
+# JSON
+
+JSON is the default serialization format in TypedRest.
+
+=== "C#"
+
+    ### Newtonsoft.Json (Default)
+
+    The default serializer uses [Newtonsoft.Json](https://www.newtonsoft.com/json) with the following settings:
+
+    - Camel-case property naming
+    - String enums with camel-case naming
+    - Null values are not serialized
+    - Automatic type name handling
+
+    ```csharp
+    var endpoint = new EntryEndpoint(new Uri("http://example.com/"));
+    // Uses NewtonsoftJsonSerializer by default
+    ```
+
+    To customize the serializer settings:
+
+    ```csharp
+    var serializer = new NewtonsoftJsonSerializer();
+    serializer.SerializerSettings.DateFormatString = "yyyy-MM-dd";
+
+    var endpoint = new EntryEndpoint(
+        new Uri("http://example.com/"),
+        serializer: serializer);
+    ```
+
+    ### System.Text.Json
+
+    You can also use the `System.Text.Json` serializer with the `TypedRest.SystemTextJson` NuGet package:
+
+    !!! note
+        The `TypedRest.SystemTextJson` package version should match your main `TypedRest` package version. Both packages follow the same versioning scheme.
+
+    Default settings:
+
+    - Web defaults (camel-case property naming)
+    - Null values are not serialized when writing
+
+    Basic usage:
+
+    ```csharp
+    using TypedRest.Serializers;
+
+    var serializer = new SystemTextJsonSerializer();
+    var endpoint = new EntryEndpoint(
+        new Uri("http://example.com/"),
+        serializer: serializer);
+    ```
+
+    To customize the serializer options:
+
+    ```csharp
+    var serializer = new SystemTextJsonSerializer();
+    serializer.Options.WriteIndented = true;
+    serializer.Options.Converters.Add(new JsonStringEnumConverter());
+
+    var endpoint = new EntryEndpoint(
+        new Uri("http://example.com/"),
+        serializer: serializer);
+    ```
+
+=== "TypeScript"
+
+    TypeScript uses the native `JSON.stringify()` and `JSON.parse()` methods:
+
+    ```typescript
+    const endpoint = new EntryEndpoint(new URL("http://example.com/"));
+    // Uses JsonSerializer by default
+    ```
+
+    ### Custom Serializers
+
+    You can implement the `Serializer` interface for custom serialization:
+
+    ```typescript
+    import { Serializer } from "typedrest";
+
+    class MySerializer implements Serializer {
+        readonly supportedMediaTypes = ["application/json"];
+
+        serialize<T>(entity: T): string {
+            // Custom serialization logic
+            return JSON.stringify(entity);
+        }
+
+        deserialize<T>(text: string): T {
+            // Custom deserialization logic
+            return JSON.parse(text) as T;
+        }
+    }
+
+    const endpoint = new EntryEndpoint(
+        new URL("http://example.com/"),
+        new MySerializer());
+    ```
+
+## Content type
+
+TODO: TypedRest automatically handle custom media types that end with `+json` (e.g., `application/vnd.api+json`, `application/hal+json`). These are treated as JSON and deserialized using the configured JSON serializer.

docs/serializers/xml.md

@@ -0,0 +1,22 @@
+# XML
+
+XML serialization is available in the .NET implementation of TypedRest.
+
+=== "C#"
+    TODO: The XML serializer uses .NET's built-in `System.Xml.Serialization.XmlSerializer`:
+
+    ```csharp
+    using TypedRest.Serializers;
+
+    var serializer = new XmlSerializer();
+    var endpoint = new EntryEndpoint(
+        new Uri("http://example.com/"),
+        serializer: serializer);
+    ```
+
+## Content type
+
+TODO: The serializer handles the following content types:
+
+- `application/xml`
+- `text/xml`