Improved Serializer documentation

Author: bastianeicher

docs/serializers/.pages

@@ -3,3 +3,4 @@ nav:
   - json.md
   - bson.md
   - xml.md
+  - custom.md

docs/serializers/bson.md

@@ -1,5 +1,7 @@
 # BSON
 
+BSON (Binary JSON) serialization is available in the .NET implementation of TypedRest.
+
 === "C#"
 
     The BSON serializer provides efficient binary serialization using [Newtonsoft.Json](https://www.newtonsoft.com/json)'s BSON support:
@@ -16,3 +18,7 @@
     - String enums with camel-case naming
     - Null values are not serialized
     - Automatic type name handling
+
+## Content type
+
+The serializer handles the `application/bson` content type.

docs/serializers/custom.md

@@ -0,0 +1,175 @@
+# Custom serializers
+
+If none of the [built-in serializers](index.md) fits your needs, you can implement your own.
+
+## Implement the interface
+
+Implement the platform's `Serializer` interface (or appropriate base type):
+
+=== "C#"
+
+    On .NET, TypedRest uses `MediaTypeFormatter` from the `System.Net.Http.Formatting` family. Derive from `MediaTypeFormatter` (or one of its specializations) and override the read/write methods.
+
+    ```csharp
+    using System.Net.Http.Formatting;
+
+    public class MySerializer : MediaTypeFormatter
+    {
+        public MySerializer()
+        {
+            SupportedMediaTypes.Add(new("application/my-format"));
+        }
+
+        public override bool CanReadType(Type type) => true;
+        public override bool CanWriteType(Type type) => true;
+
+        // Override ReadFromStreamAsync and WriteToStreamAsync to implement
+        // custom (de)serialization logic.
+    }
+    ```
+
+=== "Java"
+
+    Implement the `net.typedrest.serializers.Serializer` interface or derive from `AbstractJsonSerializer` for JSON-based formats:
+
+    ```java
+    import net.typedrest.serializers.Serializer;
+    import okhttp3.MediaType;
+    import okhttp3.RequestBody;
+    import okhttp3.ResponseBody;
+    import java.util.List;
+
+    public class MySerializer implements Serializer {
+        private static final MediaType MEDIA_TYPE = MediaType.get("application/my-format");
+
+        @Override
+        public List<MediaType> getSupportedMediaTypes() {
+            return List.of(MEDIA_TYPE);
+        }
+
+        @Override
+        public <T> RequestBody serialize(T entity, Class<T> type) {
+            // Custom serialization logic
+            return RequestBody.create(toBytes(entity), MEDIA_TYPE);
+        }
+
+        @Override
+        public <T> RequestBody serializeList(Iterable<T> entities, Class<T> type) {
+            // Custom serialization logic
+            return RequestBody.create(toBytes(entities), MEDIA_TYPE);
+        }
+
+        @Override
+        public <T> T deserialize(ResponseBody body, Class<T> type) {
+            // Custom deserialization logic
+            return fromBytes(body.bytes(), type);
+        }
+
+        @Override
+        public <T> List<T> deserializeList(ResponseBody body, Class<T> type) {
+            // Custom deserialization logic
+            return fromBytesAsList(body.bytes(), type);
+        }
+    }
+    ```
+
+=== "Kotlin"
+
+    Implement the `net.typedrest.serializers.Serializer` interface or derive from `AbstractJsonSerializer` for JSON-based formats:
+
+    ```kotlin
+    import net.typedrest.serializers.Serializer
+    import okhttp3.MediaType
+    import okhttp3.MediaType.Companion.toMediaType
+    import okhttp3.RequestBody
+    import okhttp3.RequestBody.Companion.toRequestBody
+    import okhttp3.ResponseBody
+
+    class MySerializer : Serializer {
+        private val mediaType = "application/my-format".toMediaType()
+
+        override val supportedMediaTypes: List<MediaType> = listOf(mediaType)
+
+        override fun <T> serialize(entity: T, type: Class<T>): RequestBody =
+            toBytes(entity).toRequestBody(mediaType)
+
+        override fun <T> serializeList(entities: Iterable<T>, type: Class<T>): RequestBody =
+            toBytes(entities).toRequestBody(mediaType)
+
+        override fun <T> deserialize(body: ResponseBody, type: Class<T>): T? =
+            fromBytes(body.bytes(), type)
+
+        override fun <T> deserializeList(body: ResponseBody, type: Class<T>): List<T>? =
+            fromBytesAsList(body.bytes(), type)
+    }
+    ```
+
+=== "TypeScript"
+
+    Implement the `Serializer` interface from the `typedrest` package:
+
+    ```typescript
+    import { Serializer } from "typedrest";
+
+    class MySerializer implements Serializer {
+        readonly supportedMediaTypes = ["application/my-format"];
+
+        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;
+        }
+    }
+    ```
+
+## Content negotiation
+
+The `supportedMediaTypes` property lists the MIME types this serializer can handle. TypedRest uses this information to:
+
+- Set the `Content-Type` header when sending requests.
+- Set the `Accept` header when receiving responses.
+- Pick the right serializer for a response based on its `Content-Type` header (when multiple serializers are configured).
+
+The first entry in the list is used as the default for outgoing requests.
+
+## Register the serializer
+
+Pass an instance of your serializer to the [entry endpoint](../endpoints/entry.md) constructor:
+
+=== "C#"
+
+    ```csharp
+    var endpoint = new EntryEndpoint(
+        new Uri("http://example.com/"),
+        serializer: new MySerializer());
+    ```
+
+=== "Java"
+
+    ```java
+    EntryEndpoint endpoint = new EntryEndpoint(
+        URI.create("http://example.com/"),
+        new MySerializer());
+    ```
+
+=== "Kotlin"
+
+    ```kotlin
+    val endpoint = EntryEndpoint(
+        URI.create("http://example.com/"),
+        serializer = MySerializer())
+    ```
+
+=== "TypeScript"
+
+    ```typescript
+    const endpoint = new EntryEndpoint(
+        new URL("http://example.com/"),
+        new MySerializer());
+    ```
+
+All child endpoints created from this entry endpoint automatically inherit the serializer.

docs/serializers/index.md

@@ -2,13 +2,15 @@
 
 Serializers control how entities are serialized when sending requests and deserialized when receiving responses.
 
-TypedRest provides built-in serializers for various transport formats:
+TypedRest provides serializers for various transport formats:
 
-- [JSON](json.md)
-- [BSON](bson.md)
-- [XML](xml.md)
+| Format          | C#/.NET  | Java/Kotlin | TypeScript |
+| --------------- | -------- | ----------- | ---------- |
+| [JSON](json.md) | Built-in | Built-in    | Built-in   |
+| [XML](xml.md)   | Built-in | Built-in    |            |
+| [BSON](bson.md) | Built-in |             |            |
 
-You can also create and use custom serializers.
+You can also create and use [custom serializers](custom.md).
 
 ## Inheritance
 

docs/serializers/json.md

@@ -34,11 +34,7 @@ JSON is the default serialization format in TypedRest.
 
     **System.Text.Json**
 
-    You can also use the [System.Text.Json](https://learn.microsoft.com/en-us/dotnet/api/system.text.json) serializer with the [TypedRest.SystemTextJson](https://www.nuget.org/packages/TypedRest.SystemTextJson) NuGet package:
-
-    !!! note
-        The `TypedRest.SystemTextJson` package version should match your main `TypedRest` package version. Both packages follow the same versioning scheme.
-
+    You can also use the [System.Text.Json](https://learn.microsoft.com/en-us/dotnet/api/system.text.json) serializer with the [TypedRest.SystemTextJson](https://www.nuget.org/packages/TypedRest.SystemTextJson) NuGet package.
     Default settings:
 
     - Web defaults (camel-case property naming)
@@ -76,28 +72,6 @@ JSON is the default serialization format in TypedRest.
     // Uses JsonSerializer by default
     ```
 
-    **Custom serializers**
-
-    You can implement the `Serializer` interface for custom serialization:
-
-    ```typescript
-    import { Serializer } from "typedrest";
+## Content type
 
-    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());
-    ```
+The serializer handles the `application/json` content type. TypedRest also automatically treats custom media types ending in `+json` (e.g., `application/vnd.api+json`, `application/hal+json`) as JSON and deserializes them using the configured JSON serializer.

docs/serializers/xml.md

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