Merge branch 'extend-definitions'

Andrea Fiore · Andrea Fiore · commit dca8d3264a71 · 2017-01-14T19:41:18.000Z
diff --git a/README.md b/README.md
@@ -286,7 +286,7 @@ groups into a single Swagger API description.
 
 ``` {.scala}
 scala> PathGroup.aggregate(apiInfo, List(PetsRoute, DinosRoute))
-res13: cats.data.ValidatedNel[com.timeout.docless.swagger.SchemaError,com.timeout.docless.swagger.APISchema] = Invalid(NonEmptyList(MissingDefinition(ResponseRef(TypeRef(Dino),/dinos/{id},Get))))
+res13: cats.data.ValidatedNel[com.timeout.docless.swagger.SchemaError,com.timeout.docless.swagger.APISchema] = Invalid(NonEmptyList(MissingDefinition(RefWithContext(TypeRef(Dino,None),ResponseContext(Get,/dinos/{id})))))
 ```
 
 The `aggregate` method will also verify that the schema definitions
diff --git a/src/main/scala/com/timeout/docless/encoders/Swagger.scala b/src/main/scala/com/timeout/docless/encoders/Swagger.scala
@@ -75,14 +75,14 @@ object Swagger {
   }
 
   implicit val schemaRefEnc = Encoder.instance[JsonSchema.Ref] {
-    case ArrayRef(id) =>
+    case ArrayRef(id, _) =>
       Json.obj(
         "type" -> Json.fromString("array"),
         "items" -> Json.obj(
           "$ref" -> Json.fromString(s"#/definitions/$id")
         )
       )
-    case TypeRef(id) =>
+    case TypeRef(id, _) =>
       Json.obj("$ref" -> Json.fromString(s"#/definitions/$id"))
   }
 
diff --git a/src/main/scala/com/timeout/docless/schema/JsonSchema.scala b/src/main/scala/com/timeout/docless/schema/JsonSchema.scala
@@ -1,5 +1,6 @@
 package com.timeout.docless.schema
 
+import com.timeout.docless.schema.JsonSchema.NamedDefinition
 import com.timeout.docless.swagger.Responses.Response
 import io.circe._
 import io.circe.syntax._
@@ -19,6 +20,9 @@ trait JsonSchema[A] extends JsonSchema.HasRef {
 
   def relatedDefinitions: Set[JsonSchema.Definition]
 
+  def fieldDefinitions: Set[JsonSchema.NamedDefinition] =
+    relatedDefinitions.collect { case d: NamedDefinition => d }
+
   def jsonObject: JsonObject
 
   def asJson: Json = jsonObject.asJson
@@ -30,8 +34,16 @@ trait JsonSchema[A] extends JsonSchema.HasRef {
 
   def asJsonRef: Json = asObjectRef.asJson
 
-  lazy val definition: JsonSchema.Definition =
-    JsonSchema.Definition(id, asJson)
+  def namedDefinition(fieldName: String): NamedDefinition =
+    JsonSchema.NamedDefinition(
+      id,
+      fieldName,
+      relatedDefinitions.map(_.asRef),
+      asJson
+    )
+
+  lazy val definition: JsonSchema.UnnamedDefinition =
+    JsonSchema.UnnamedDefinition(id, relatedDefinitions.map(_.asRef), asJson)
 
   def definitions: Set[JsonSchema.Definition] =
     relatedDefinitions + definition
@@ -49,26 +61,43 @@ object JsonSchema
     with derive.CoprodInstances {
   trait HasRef {
     def id: String
-    def asRef: Ref      = TypeRef(id)
-    def asArrayRef: Ref = ArrayRef(id)
+    def asRef: Ref      = TypeRef(id, None)
+    def asArrayRef: Ref = ArrayRef(id, None)
   }
 
-  case class Definition(id: String, json: Json) extends HasRef
+  sealed trait Definition extends HasRef {
+    def id: String
+    def json: Json
+    def relatedRefs: Set[Ref]
+  }
+
+  case class UnnamedDefinition(id: String, relatedRefs: Set[Ref], json: Json)
+      extends Definition
+
+  case class NamedDefinition(id: String,
+                             fieldName: String,
+                             relatedRefs: Set[Ref],
+                             json: Json)
+      extends Definition {
+    override def asRef      = TypeRef(id, Some(fieldName))
+    override def asArrayRef = ArrayRef(id, Some(fieldName))
+  }
 
   sealed trait Ref {
     def id: String
+    def fieldName: Option[String]
   }
 
-  case class TypeRef(id: String) extends Ref
+  case class TypeRef(id: String, fieldName: Option[String]) extends Ref
   object TypeRef {
-    def apply(definition: Definition): TypeRef = TypeRef(definition.id)
-    def apply(schema: JsonSchema[_]): TypeRef  = TypeRef(schema.id)
+    def apply(definition: Definition): TypeRef = TypeRef(definition.id, None)
+    def apply(schema: JsonSchema[_]): TypeRef  = TypeRef(schema.id, None)
   }
 
-  case class ArrayRef(id: String) extends Ref
+  case class ArrayRef(id: String, fieldName: Option[String]) extends Ref
   object ArrayRef {
-    def apply(definition: Definition): ArrayRef = ArrayRef(definition.id)
-    def apply(schema: JsonSchema[_]): ArrayRef  = ArrayRef(schema.id)
+    def apply(definition: Definition): ArrayRef = ArrayRef(definition.id, None)
+    def apply(schema: JsonSchema[_]): ArrayRef  = ArrayRef(schema.id, None)
   }
 
   trait PatternProperty[K] {
diff --git a/src/main/scala/com/timeout/docless/schema/derive/HListInstances.scala b/src/main/scala/com/timeout/docless/schema/derive/HListInstances.scala
@@ -18,15 +18,17 @@ trait HListInstances {
       lazyHSchema: Lazy[JsonSchema[H]],
       lazyTSchema: Lazy[JsonSchema[T]]
   ): JsonSchema[FieldType[K, H] :: T] = instanceAndRelated {
-    val hSchema = lazyHSchema.value
-    val tSchema = lazyTSchema.value
+    val fieldName = witness.value.name
+    val hSchema   = lazyHSchema.value
+    val tSchema   = lazyTSchema.value
     val (hValue, related) =
       if (hSchema.inline)
         hSchema.asJson -> tSchema.relatedDefinitions
       else
-        hSchema.asJsonRef -> (tSchema.relatedDefinitions + hSchema.definition)
+        hSchema.asJsonRef -> (tSchema.relatedDefinitions + hSchema
+          .namedDefinition(fieldName))
 
-    val hField  = witness.value.name -> hValue
+    val hField  = fieldName -> hValue
     val tFields = tSchema.jsonObject.toList
 
     JsonObject.fromIterable(hField :: tFields) -> related
diff --git a/src/main/scala/com/timeout/docless/swagger/Path.scala b/src/main/scala/com/timeout/docless/swagger/Path.scala
@@ -1,31 +1,16 @@
 package com.timeout.docless.swagger
 
-import com.timeout.docless.schema.JsonSchema.Ref
 import cats.syntax.foldable._
 import cats.instances.list._
 import cats.instances.map._
-import com.timeout.docless.swagger.Path._
-
-object Path {
-  sealed trait RefWithContext {
-    def path: String
-    def ref: Ref
-  }
-
-  case class ParamRef(ref: Ref, path: String, param: String)
-      extends RefWithContext
-
-  case class ResponseRef(ref: Ref, path: String, method: Method)
-      extends RefWithContext
-}
 
 case class Path(id: String,
                 parameters: List[OperationParameter] = Nil,
                 operations: Map[Method, Operation] = Map.empty)
     extends ParamSetters[Path] {
 
-  private def paramRef(p: OperationParameter): Option[ParamRef] =
-    p.schema.map(ParamRef(_, id, p.name))
+  private def paramRef(p: OperationParameter): Option[RefWithContext] =
+    p.schema.map(RefWithContext.param(_, id, p.name))
 
   def paramRefs: Set[RefWithContext] =
     parameters.flatMap(paramRef).toSet ++
@@ -35,7 +20,7 @@ case class Path(id: String,
     operations.flatMap {
       case (m, op) =>
         val resps = op.responses.default :: op.responses.byStatusCode.values.toList
-        resps.flatMap(_.schema.map(ResponseRef(_, id, m)))
+        resps.flatMap { _.schema.map(RefWithContext.response(_, m, id)) }
     }.toSet
 
   def refs: Set[RefWithContext] = responseRefs ++ paramRefs
diff --git a/src/main/scala/com/timeout/docless/swagger/PathGroup.scala b/src/main/scala/com/timeout/docless/swagger/PathGroup.scala
@@ -6,8 +6,7 @@ import cats.syntax.eq._
 import cats.syntax.foldable._
 import cats.syntax.monoid._
 import cats.{Eq, Monoid}
-import com.timeout.docless.schema.JsonSchema.Definition
-import com.timeout.docless.swagger.Path.RefWithContext
+import com.timeout.docless.schema.JsonSchema.{Definition, TypeRef}
 
 trait PathGroup {
   def params: List[OperationParameter] = Nil
@@ -24,16 +23,26 @@ object PathGroup {
       info: Info,
       groups: List[PathGroup]
   ): ValidatedNel[SchemaError, APISchema] = {
-    val g = groups.combineAll
+    val g          = groups.combineAll
+    val allDefs    = g.definitions
+    val definedIds = allDefs.map(_.id).toSet
 
     def isDefined(ctx: RefWithContext): Boolean =
-      g.definitions.exists(_.id === ctx.ref.id)
+      allDefs.exists(_.id === ctx.ref.id)
+
+    val missingDefinitions =
+      allDefs.foldMap { d =>
+        d.relatedRefs.collect {
+          case r @ TypeRef(id, _) if !definedIds.exists(_ === id) =>
+            SchemaError.missingDefinition(RefWithContext.definition(r, d))
+        }
+      }
 
     val errors =
       g.paths
         .foldMap(_.refs.filterNot(isDefined))
         .map(SchemaError.missingDefinition)
-        .toList
+        .toList ++ missingDefinitions
 
     if (errors.nonEmpty)
       Validated.invalid[NonEmptyList[SchemaError], APISchema](
diff --git a/src/main/scala/com/timeout/docless/swagger/RefWithContext.scala b/src/main/scala/com/timeout/docless/swagger/RefWithContext.scala
@@ -0,0 +1,28 @@
+package com.timeout.docless.swagger
+
+import com.timeout.docless.schema.JsonSchema.{Definition, Ref}
+
+object RefWithContext {
+  trait PathContext {
+    def path: String
+  }
+
+  sealed trait Context
+  case class DefinitionContext(definition: Definition) extends Context
+  case class ParamContext(param: String, path: String)
+      extends Context
+      with PathContext
+  case class ResponseContext(method: Method, path: String)
+      extends Context
+      with PathContext
+
+  def definition(ref: Ref, d: Definition) =
+    RefWithContext(ref, DefinitionContext(d))
+  def param(ref: Ref, param: String, path: String) =
+    RefWithContext(ref, ParamContext(param, path))
+  def response(ref: Ref, method: Method, path: String) =
+    RefWithContext(ref, ResponseContext(method, path))
+}
+
+import RefWithContext.Context
+case class RefWithContext(ref: Ref, context: Context)
diff --git a/src/main/scala/com/timeout/docless/swagger/SchemaError.scala b/src/main/scala/com/timeout/docless/swagger/SchemaError.scala
@@ -1,7 +1,7 @@
 package com.timeout.docless.swagger
 
 import cats.Show
-import com.timeout.docless.swagger.Path.{ParamRef, RefWithContext, ResponseRef}
+import RefWithContext._
 
 sealed trait SchemaError
 
@@ -11,9 +11,12 @@ object SchemaError {
     MissingDefinition(ctx)
 
   implicit val mdShow: Show[SchemaError] = Show.show {
-    case MissingDefinition(ParamRef(r, path, param)) =>
+    case MissingDefinition(RefWithContext(r, DefinitionContext(d))) =>
+      val fieldName = r.fieldName.fold("")(fld => s"(in field name: $fld)")
+      s"${d.id}: cannot find a definition for '${r.id}' $fieldName"
+    case MissingDefinition(RefWithContext(r, ParamContext(param, path))) =>
       s"$path: cannot find definition '${r.id}' for parameter name '$param'"
-    case MissingDefinition(ResponseRef(r, path, method)) =>
+    case MissingDefinition(RefWithContext(r, ResponseContext(method, path))) =>
       s"$path: cannot find response definition '${r.id}' for method '${method.entryName}'"
   }
 }
diff --git a/src/test/scala/com/timeout/docless/schema/JsonSchemaTest.scala b/src/test/scala/com/timeout/docless/schema/JsonSchemaTest.scala
@@ -111,7 +111,7 @@ class JsonSchemaTest extends FreeSpec {
           """.stripMargin) should ===(Right(schema.asJson))
 
       schema.id should ===(id[Nested])
-      schema.relatedDefinitions should ===(Set(fs.definition))
+      schema.relatedDefinitions should ===(Set(fs.namedDefinition("foo")))
     }
 
     "with types extending enumeratum.EnumEntry" - {
@@ -175,18 +175,18 @@ class JsonSchemaTest extends FreeSpec {
 
       "provides JSON definitions of the coproduct" in {
         implicit val fs: JsonSchema[Foo] = fooSchema
-        val schema                       = JsonSchema.deriveFor[ADT]
-        val ySchema                      = JsonSchema.deriveFor[A]
-        val zSchema                      = JsonSchema.deriveFor[B]
 
-        val z1Schema = JsonSchema.deriveFor[C]
+        val schema  = JsonSchema.deriveFor[ADT]
+        val aSchema = JsonSchema.deriveFor[A]
+        val bSchema = JsonSchema.deriveFor[B]
+        val cSchema = JsonSchema.deriveFor[C]
 
         schema.relatedDefinitions should ===(
           Set(
-            ySchema.definition,
-            zSchema.definition,
-            z1Schema.definition,
-            fooSchema.definition
+            aSchema.definition,
+            bSchema.definition,
+            cSchema.definition,
+            fooSchema.namedDefinition("foo")
           )
         )
       }
diff --git a/src/test/scala/com/timeout/docless/swagger/PathGroupTest.scala b/src/test/scala/com/timeout/docless/swagger/PathGroupTest.scala
@@ -4,29 +4,29 @@ import org.scalatest.{FreeSpec, Inside, Matchers}
 import cats.data.NonEmptyList
 import cats.data.Validated
 import SchemaError._
+import com.timeout.docless.schema.JsonSchema
 import com.timeout.docless.schema.JsonSchema._
 import com.timeout.docless.swagger.Method._
-import com.timeout.docless.swagger.Path._
 
 class PathGroupTest extends FreeSpec with Matchers {
   "PathGroup" - {
     val petstore = PetstoreSchema()
     val pet      = PetstoreSchema.Schemas.pet
 
-    val paths     = Path("example") :: petstore.paths.get.toList
+    val paths     = Path("/example") :: petstore.paths.get.toList
     val defs      = petstore.definitions.get.toList
     val defsNoPet = defs.filterNot(_.id === pet.id)
     val params    = petstore.parameters.get.toList
 
     val group1          = PathGroup(paths, defs, params)
-    val group2          = PathGroup(List(Path("extra")), Nil, Nil)
+    val group2          = PathGroup(List(Path("/extra")), Nil, Nil)
     val groupMissingErr = PathGroup(paths, defsNoPet, params)
 
     def err(path: String, m: Method, f: Definition => Ref): SchemaError =
-      missingDefinition(ResponseRef(f(pet.definition), path, m))
+      missingDefinition(RefWithContext.response(f(pet.definition), m, path))
 
     "aggregate" - {
-      "when some definitions are missing" - {
+      "when some top level definitions are missing" - {
         "returns the missing refs" in {
           PathGroup.aggregate(petstore.info, List(groupMissingErr)) should ===(
             Validated.invalid[NonEmptyList[SchemaError], APISchema](
@@ -40,6 +40,37 @@ class PathGroupTest extends FreeSpec with Matchers {
           )
         }
       }
+      "when some nested definitions are missing" - {
+        val info = Info("example")
+        case class Nested(name: String)
+        case class TopLevel(nested: Nested)
+
+        val schema = JsonSchema.deriveFor[TopLevel]
+        val nested = schema.relatedDefinitions.head
+
+        val paths = List(
+          "/example".Post(
+            Operation('_, "...")
+              .withParams(BodyParameter(schema = Some(schema.asRef)))
+          )
+        )
+
+        val withNested    = PathGroup(paths, schema.definitions.toList, Nil)
+        val withoutNested = PathGroup(paths, List(schema.definition), Nil)
+
+        "returns the missing refs" in {
+          PathGroup.aggregate(info, List(withNested)).isValid shouldBe true
+          PathGroup.aggregate(info, List(withoutNested)) should ===(
+            Validated.invalid[NonEmptyList[SchemaError], APISchema](
+              NonEmptyList.of(
+                MissingDefinition(
+                  RefWithContext.definition(nested.asRef, schema.definition)
+                )
+              )
+            )
+          )
+        }
+      }
       "when no definition is missing" - {
         "returns a valid api schema" in new Inside {
           inside(PathGroup.aggregate(petstore.info, List(group1, group2))) {

Original file line number	Diff line number	Diff line change
`@@ -75,14 +75,14 @@ object Swagger {`
`75`	`75`	`}`
`76`	`76`
`77`	`77`	`implicit val schemaRefEnc = Encoder.instance[JsonSchema.Ref] {`
`78`		`- case ArrayRef(id) =>`
	`78`	`+ case ArrayRef(id, _) =>`
`79`	`79`	`Json.obj(`
`80`	`80`	`"type" -> Json.fromString("array"),`
`81`	`81`	`"items" -> Json.obj(`
`82`	`82`	`"$ref" -> Json.fromString(s"#/definitions/$id")`
`83`	`83`	`)`
`84`	`84`	`)`
`85`		`- case TypeRef(id) =>`
	`85`	`+ case TypeRef(id, _) =>`
`86`	`86`	`Json.obj("$ref" -> Json.fromString(s"#/definitions/$id"))`
`87`	`87`	`}`
`88`	`88`