From cf9467ebe538f754c1753cf5582ce61da95b6fff Mon Sep 17 00:00:00 2001
From: Nabil Abdel-Hafeez <7283535+987Nabil@users.noreply.github.com>
Date: Tue, 18 Jun 2024 14:31:41 +0200
Subject: [PATCH] Add `description` annotation content to docs for open API
 (#2722) (#2914)

---
 .../endpoint/openapi/OpenAPIGenSpec.scala     | 96 +++++++------------
 .../http/endpoint/openapi/JsonSchema.scala    |  1 +
 2 files changed, 36 insertions(+), 61 deletions(-)

diff --git a/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala b/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala
index 9b037371b2..fcc06023b6 100644
--- a/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala
+++ b/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala
@@ -4,7 +4,7 @@ import zio.json.ast.Json
 import zio.test._
 import zio.{Scope, ZIO}
 
-import zio.schema.annotation.{caseName, discriminatorName, noDiscriminator, optionalField, transientField}
+import zio.schema.annotation._
 import zio.schema.{DeriveSchema, Schema}
 
 import zio.http.Method.{GET, POST}
@@ -113,6 +113,7 @@ object OpenAPIGenSpec extends ZIOSpecDefault {
     case class NestedThree(name: String) extends SimpleNestedSealedTrait
   }
 
+  @description("A simple payload")
   case class Payload(content: String)
 
   object Payload {
@@ -2251,36 +2252,29 @@ object OpenAPIGenSpec extends ZIOSpecDefault {
                              |    "/root/{name}" : {
                              |      "get" : {
                              |        "parameters" : [
-                             |
-                             |            {
+                             |          {
                              |            "name" : "name",
                              |            "in" : "path",
                              |            "required" : true,
-                             |            "schema" :
-                             |              {
-                             |              "type" :
-                             |                "string"
+                             |            "schema" : {
+                             |              "type" : "string"
                              |            },
                              |            "examples" : {
-                             |              "hi" :
-                             |                {
+                             |              "hi" : {
                              |                "value" : "name_value"
                              |              }
                              |            },
                              |            "style" : "simple"
                              |          }
                              |        ],
-                             |        "requestBody" :
-                             |          {
+                             |        "requestBody" : {
                              |          "content" : {
                              |            "application/json" : {
-                             |              "schema" :
-                             |                {
+                             |              "schema" : {
                              |                "$ref" : "#/components/schemas/Payload"
                              |              },
                              |              "examples" : {
-                             |                "hi" :
-                             |                  {
+                             |                "hi" : {
                              |                  "value" : {
                              |                    "content" : "input"
                              |                  }
@@ -2291,14 +2285,11 @@ object OpenAPIGenSpec extends ZIOSpecDefault {
                              |          "required" : true
                              |        },
                              |        "responses" : {
-                             |          "200" :
-                             |            {
+                             |          "200" : {
                              |            "content" : {
                              |              "application/json" : {
-                             |                "schema" :
-                             |                  {
-                             |                  "type" :
-                             |                    "string"
+                             |                "schema" : {
+                             |                  "type" : "string"
                              |                }
                              |              }
                              |            }
@@ -2309,19 +2300,17 @@ object OpenAPIGenSpec extends ZIOSpecDefault {
                              |  },
                              |  "components" : {
                              |    "schemas" : {
-                             |      "Payload" :
-                             |        {
-                             |        "type" :
-                             |          "object",
+                             |      "Payload" : {
+                             |        "type" : "object",
                              |        "properties" : {
                              |          "content" : {
-                             |            "type" :
-                             |              "string"
+                             |            "type" : "string"
                              |          }
                              |        },
                              |        "required" : [
                              |          "content"
-                             |        ]
+                             |        ],
+                             |        "description" : "A simple payload"
                              |      }
                              |    }
                              |  }
@@ -2351,55 +2340,45 @@ object OpenAPIGenSpec extends ZIOSpecDefault {
                              |    "/root/{name}" : {
                              |      "get" : {
                              |        "parameters" : [
-                             |
-                             |            {
+                             |          {
                              |            "name" : "name",
                              |            "in" : "path",
                              |            "required" : true,
-                             |            "schema" :
-                             |              {
-                             |              "type" :
-                             |                "string"
+                             |            "schema" : {
+                             |              "type" : "string"
                              |            },
                              |            "examples" : {
-                             |              "hi" :
-                             |                {
+                             |              "hi" : {
                              |                "value" : "name_value"
                              |              },
-                             |              "ho" :
-                             |                {
+                             |              "ho" : {
                              |                "value" : "name_value2"
                              |              }
                              |            },
                              |            "style" : "simple"
                              |          }
                              |        ],
-                             |        "requestBody" :
-                             |          {
+                             |        "requestBody" : {
                              |          "content" : {
                              |            "application/json" : {
-                             |              "schema" :
-                             |                {
+                             |              "schema" : {
                              |                "anyOf" : [
                              |                  {
                              |                    "$ref" : "#/components/schemas/Payload"
                              |                  },
                              |                  {
-                             |                    "type" :
-                             |                      "string"
+                             |                    "type" : "string"
                              |                  }
                              |                ],
                              |                "description" : ""
                              |              },
                              |              "examples" : {
-                             |                "hi" :
-                             |                  {
+                             |                "hi" : {
                              |                  "value" : {
                              |                    "content" : "input"
                              |                  }
                              |                },
-                             |                "ho" :
-                             |                  {
+                             |                "ho" : {
                              |                  "value" : "input"
                              |                }
                              |              }
@@ -2408,14 +2387,11 @@ object OpenAPIGenSpec extends ZIOSpecDefault {
                              |          "required" : true
                              |        },
                              |        "responses" : {
-                             |          "200" :
-                             |            {
+                             |          "200" : {
                              |            "content" : {
                              |              "application/json" : {
-                             |                "schema" :
-                             |                  {
-                             |                  "type" :
-                             |                    "string"
+                             |                "schema" : {
+                             |                  "type" : "string"
                              |                }
                              |              }
                              |            }
@@ -2426,19 +2402,17 @@ object OpenAPIGenSpec extends ZIOSpecDefault {
                              |  },
                              |  "components" : {
                              |    "schemas" : {
-                             |      "Payload" :
-                             |        {
-                             |        "type" :
-                             |          "object",
+                             |      "Payload" : {
+                             |        "type" : "object",
                              |        "properties" : {
                              |          "content" : {
-                             |            "type" :
-                             |              "string"
+                             |            "type" : "string"
                              |          }
                              |        },
                              |        "required" : [
                              |          "content"
-                             |        ]
+                             |        ],
+                             |        "description" : "A simple payload"
                              |      }
                              |    }
                              |  }
diff --git a/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/JsonSchema.scala b/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/JsonSchema.scala
index ca574fc805..205fc82641 100644
--- a/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/JsonSchema.scala
+++ b/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/JsonSchema.scala
@@ -523,6 +523,7 @@ object JsonSchema {
               .map(_.name),
           )
           .deprecated(deprecated(record))
+          .description(record.annotations.collectFirst { case description(value) => value })
       case collection: Schema.Collection[_, _]                                                    =>
         collection match {
           case Schema.Sequence(elementSchema, _, _, _, _) =>