From 36b8b57fd5dd0e602ad53e4fc5c3d5fce2a6fa40 Mon Sep 17 00:00:00 2001 From: Bastian Eicher Date: Mon, 9 Feb 2026 17:56:02 +0100 Subject: [PATCH 1/3] Added documentation for "Serializers" --- docs/.pages | 2 +- docs/serializers/.pages | 5 ++ docs/serializers/bson.md | 27 ++++++++++ docs/serializers/index.md | 34 +++++++++++++ docs/serializers/json.md | 104 ++++++++++++++++++++++++++++++++++++++ docs/serializers/xml.md | 22 ++++++++ 6 files changed, 193 insertions(+), 1 deletion(-) create mode 100644 docs/serializers/.pages create mode 100644 docs/serializers/bson.md create mode 100644 docs/serializers/json.md create mode 100644 docs/serializers/xml.md diff --git a/docs/.pages b/docs/.pages index 2e971cc..a999859 100644 --- a/docs/.pages +++ b/docs/.pages @@ -4,7 +4,7 @@ nav: - setup - endpoints - serializers - - error-handling - link-handling + - error-handling - code-generation - imprint.md diff --git a/docs/serializers/.pages b/docs/serializers/.pages new file mode 100644 index 0000000..7ab032d --- /dev/null +++ b/docs/serializers/.pages @@ -0,0 +1,5 @@ +nav: + - index.md + - json.md + - bson.md + - xml.md diff --git a/docs/serializers/bson.md b/docs/serializers/bson.md new file mode 100644 index 0000000..c93b8f4 --- /dev/null +++ b/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. diff --git a/docs/serializers/index.md b/docs/serializers/index.md index b6ee2b7..91a65b9 100644 --- a/docs/serializers/index.md +++ b/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(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(client, "./contacts"); + // contacts.serializer is automatically set to the same CustomSerializer + ``` + +This inheritance ensures consistent serialization behavior across your entire endpoint hierarchy. diff --git a/docs/serializers/json.md b/docs/serializers/json.md new file mode 100644 index 0000000..6349a0b --- /dev/null +++ b/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(entity: T): string { + // Custom serialization logic + return JSON.stringify(entity); + } + + deserialize(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. diff --git a/docs/serializers/xml.md b/docs/serializers/xml.md new file mode 100644 index 0000000..509cd61 --- /dev/null +++ b/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` From 147f7eeed53451a5cf37dd806e2c06ed7660a56c Mon Sep 17 00:00:00 2001 From: Bastian Eicher Date: Sat, 2 Aug 2025 13:58:30 +0200 Subject: [PATCH 2/3] Added "Testing" section --- docs/.pages | 1 + docs/index.md | 3 +++ docs/testing/index.md | 3 +++ docs/testing/integration-tests.md | 3 +++ docs/testing/unit-tests.md | 3 +++ 5 files changed, 13 insertions(+) create mode 100644 docs/testing/index.md create mode 100644 docs/testing/integration-tests.md create mode 100644 docs/testing/unit-tests.md diff --git a/docs/.pages b/docs/.pages index a999859..28028d3 100644 --- a/docs/.pages +++ b/docs/.pages @@ -6,5 +6,6 @@ nav: - serializers - link-handling - error-handling + - testing - code-generation - imprint.md diff --git a/docs/index.md b/docs/index.md index deed72f..0e456c8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -124,5 +124,8 @@ TypedRest helps you build type-safe, fluent-style REST API clients. Common REST [Link handling](link-handling/index.md) : How to handle relative URIs, link headers, HATEOS, etc. with TypedRest. +[Testing](testing/index.md) +: How to create unit and integration tests when using TypedRest. + [Code generation](code-generation/index.md) : Auto-generate code for TypedRest from Swagger/OpenAPI sepc. diff --git a/docs/testing/index.md b/docs/testing/index.md new file mode 100644 index 0000000..3b446c2 --- /dev/null +++ b/docs/testing/index.md @@ -0,0 +1,3 @@ +# Testing + +TODO diff --git a/docs/testing/integration-tests.md b/docs/testing/integration-tests.md new file mode 100644 index 0000000..c1e6850 --- /dev/null +++ b/docs/testing/integration-tests.md @@ -0,0 +1,3 @@ +# Integration tests + +TODO diff --git a/docs/testing/unit-tests.md b/docs/testing/unit-tests.md new file mode 100644 index 0000000..a73cb87 --- /dev/null +++ b/docs/testing/unit-tests.md @@ -0,0 +1,3 @@ +# Unit tests + +TODO From e94f5150b77f354234d4896d8b4e1d0609b27fd7 Mon Sep 17 00:00:00 2001 From: Bastian Eicher Date: Mon, 9 Feb 2026 20:27:57 +0100 Subject: [PATCH 3/3] wip --- docs/link-handling/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/link-handling/index.md b/docs/link-handling/index.md index d8a2dc7..b6b73e2 100644 --- a/docs/link-handling/index.md +++ b/docs/link-handling/index.md @@ -11,6 +11,8 @@ TypedRest supports a variety of different ways to establish links between [endpo All endpoints provide methods for resolving links: +TODO: Add full method signatures + === "C#" - `GetLinks(rel)` - Resolves all links with a specific relation type