From da237ed5d5bbcbdf51f077d7322bc27a2875e4c3 Mon Sep 17 00:00:00 2001
From: adamw <adam@warski.org>
Date: Mon, 6 Apr 2020 12:19:19 +0200
Subject: [PATCH] anyJsonCodec

---
 core/src/main/scala/sttp/tapir/Tapir.scala | 10 +++++++++-
 doc/endpoint/json.md                       | 13 +++++++++++--
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/core/src/main/scala/sttp/tapir/Tapir.scala b/core/src/main/scala/sttp/tapir/Tapir.scala
index 57f3d26e6d..a68113ada9 100644
--- a/core/src/main/scala/sttp/tapir/Tapir.scala
+++ b/core/src/main/scala/sttp/tapir/Tapir.scala
@@ -3,7 +3,7 @@ package sttp.tapir
 import java.nio.charset.{Charset, StandardCharsets}
 
 import sttp.model.{Cookie, CookieValueWithMeta, CookieWithMeta, Header, HeaderNames, MultiQueryParams, StatusCode}
-import sttp.tapir.CodecFormat.{OctetStream, TextPlain}
+import sttp.tapir.CodecFormat.{Json, OctetStream, TextPlain}
 import sttp.tapir.EndpointOutput.StatusMapping
 import sttp.tapir.internal.{ModifyMacroSupport, StatusMappingMacro}
 import sttp.tapir.model.ServerRequest
@@ -57,6 +57,14 @@ trait Tapir extends TapirDerivedInputs with ModifyMacroSupport {
   def plainBody[T: Codec[String, *, TextPlain]](charset: Charset): EndpointIO.Body[String, T] =
     EndpointIO.Body(RawBodyType.StringBody(charset), implicitly, EndpointIO.Info.empty)
 
+  /**
+    * Json codecs are usually derived from json-library-specific implicits. That's why integrations with
+    * various json libraries define `jsonBody` methods, which directly require the library-specific implicits.
+    *
+    * If you have a custom json codec, you should use this method instead.
+    */
+  def anyJsonBody[T: Codec[String, *, Json]]: EndpointIO.Body[String, T] = anyFromUtf8StringBody(implicitly[Codec[String, T, Json]])
+
   def rawBinaryBody[R: RawBodyType.Binary](implicit codec: Codec[R, R, OctetStream]): EndpointIO.Body[R, R] =
     EndpointIO.Body(implicitly[RawBodyType.Binary[R]], codec, EndpointIO.Info.empty)
   def binaryBody[R: RawBodyType.Binary, T: Codec[R, *, OctetStream]]: EndpointIO.Body[R, T] =
diff --git a/doc/endpoint/json.md b/doc/endpoint/json.md
index 4e72997cd9..557eac2875 100644
--- a/doc/endpoint/json.md
+++ b/doc/endpoint/json.md
@@ -1,10 +1,19 @@
 # Working with JSON
 
-Json values are supported through codecs which encode/decode values to json strings. However, third-party libraries are
-needed for actual json parsing/printing. Currently, [Circe](https://github.com/circe/circe), 
+Json values are supported through codecs, which encode/decode values to json strings. Most often, you'll be using a 
+third-party library to perform the actual json parsing/printing. Currently, [Circe](https://github.com/circe/circe), 
 [µPickle](http://www.lihaoyi.com/upickle/), [Spray JSON](https://github.com/spray/spray-json) and 
 [Play JSON](https://github.com/playframework/play-json) are supported.
 
+All of the integrations, when imported into scope, define a `jsonBody[T]` method. This method depends on 
+library-specific implicits being in scope, and derives from them a json codec. The derivation also requires implicit
+`Schema[T]` and `Validator[T]` instances, which should be automatically derived. For more details see documentation 
+on supporting [custom types](customtypes.html).
+
+If you have a custom, implicit `Codec[String, T, Json]` instance, you should use the `anyJsonBody[T]` method instead. 
+This description of endpoint input/output, instead of deriving a codec basing on other library-specific implicits, uses 
+the json codec that is in scope.
+
 ## Circe
 
 To use Circe add the following dependency to your project: