From 525e4354a46222499e792463968278fc4006d169 Mon Sep 17 00:00:00 2001
From: TimAndy <xuchonglei@126.com>
Date: Thu, 21 Nov 2024 14:43:08 +0800
Subject: [PATCH] Add custom json codec examples in doc file

---
 docs/doc.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/docs/doc.md b/docs/doc.md
index a463e820..c5f809be 100644
--- a/docs/doc.md
+++ b/docs/doc.md
@@ -63,6 +63,7 @@
   - [http2 server push](#http2-server-push)
   - [Define format for the log of routes](#define-format-for-the-log-of-routes)
   - [Set and get a cookie](#set-and-get-a-cookie)
+  - [Custom json codec at runtime](#custom-json-codec-at-runtime)
 - [Don't trust all proxies](#dont-trust-all-proxies)
 - [Testing](#testing)
 
@@ -2309,6 +2310,66 @@ func main() {
 }
 ```
 
+### Custom json codec at runtime
+
+Gin support custom json serialization and deserialization logic without using compile tags.
+
+1. Define a custom struct implements the `api.JsonApi` interface.
+
+2. Before your engine starts, assign values to `json.Api` using the custom struct.
+
+```go
+package main
+
+import (
+    "io"
+
+    "github.com/gin-gonic/gin"
+    "github.com/gin-gonic/gin/codec/api"
+    "github.com/gin-gonic/gin/codec/json"
+    jsoniter "github.com/json-iterator/go"
+)
+
+var customConfig = jsoniter.Config{
+    EscapeHTML:             true,
+    SortMapKeys:            true,
+    ValidateJsonRawMessage: true,
+}.Froze()
+
+// implement api.JsonApi
+type customJsonApi struct {
+}
+
+func (j customJsonApi) Marshal(v any) ([]byte, error) {
+    return customConfig.Marshal(v)
+}
+
+func (j customJsonApi) Unmarshal(data []byte, v any) error {
+    return customConfig.Unmarshal(data, v)
+}
+
+func (j customJsonApi) MarshalIndent(v any, prefix, indent string) ([]byte, error) {
+    return customConfig.MarshalIndent(v, prefix, indent)
+}
+
+func (j customJsonApi) NewEncoder(writer io.Writer) api.JsonEncoder {
+    return customConfig.NewEncoder(writer)
+}
+
+func (j customJsonApi) NewDecoder(reader io.Reader) api.JsonDecoder {
+    return customConfig.NewDecoder(reader)
+}
+
+func main() {
+    //Replace the default json api
+    json.Api = customJsonApi{}
+
+    //Start your gin engine
+    router := gin.Default()
+    router.Run(":8080")
+}
+```
+
 ## Don't trust all proxies
 
 Gin lets you specify which headers to hold the real client IP (if any),