Track related refs in definition

Author: Andrea Fiore

Diff for: 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),ResponseContext(Get,/dinos/{id})))))
 ```
 
 The `aggregate` method will also verify that the schema definitions

Diff for: src/main/scala/com/timeout/docless/schema/JsonSchema.scala

@@ -31,7 +31,7 @@ trait JsonSchema[A] extends JsonSchema.HasRef {
   def asJsonRef: Json = asObjectRef.asJson
 
   lazy val definition: JsonSchema.Definition =
-    JsonSchema.Definition(id, asJson)
+    JsonSchema.Definition(id, relatedDefinitions.map(_.asRef), asJson)
 
   def definitions: Set[JsonSchema.Definition] =
     relatedDefinitions + definition
@@ -53,7 +53,8 @@ object JsonSchema
     def asArrayRef: Ref = ArrayRef(id)
   }
 
-  case class Definition(id: String, json: Json) extends HasRef
+  case class Definition(id: String, relatedRefs: Set[Ref], json: Json)
+      extends HasRef
 
   sealed trait Ref {
     def id: String

Diff for: 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 for: 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 for: 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 for: 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,11 @@ object SchemaError {
     MissingDefinition(ctx)
 
   implicit val mdShow: Show[SchemaError] = Show.show {
-    case MissingDefinition(ParamRef(r, path, param)) =>
+    case MissingDefinition(RefWithContext(r, DefinitionContext(d))) =>
+      s"${d.id}: cannot find a field definition for: '${r.id}'"
+    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 for: 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))) {