SchemaComparator.compare scaladoc

apispec-model/src/main/scala/sttp/apispec/validation/SchemaComparator.scala

@@ -9,6 +9,28 @@ import scala.collection.mutable
 object SchemaComparator {
   final val RefPrefix = "#/components/schemas/"
 
+  /**
+   * Compares two schemas for compatibility. More precisely, checks if data that is valid according to [[writerSchema]]
+   * is also valid according to [[readerSchema]]. If not, a list of compatibility issues is returned.
+   *
+   * Determining compatibility (or incompatibility) of arbitrary schemas with certainty is non-trivial, or outright
+   * impossible in general. For this reason, this method works in a "best effort" manner, assuming that the schemas
+   * match one of the typical schema patterns generated by frameworks like `tapir`. In more complex situations,
+   * the comparator simply falls back to comparing schemas by plain equality, or returns a [[GeneralSchemaMismatch]],
+   * which indicates comparator's inability to definitely determine compatibility or incompatibility of the schemas.
+   *
+   * In practice, the comparator is designed to detect typical changes that may appear in schemas during API evolution,
+   * e.g. adding new fields, changing types, etc.
+   *
+   * Before being compared, all schemas are stripped of keywords which do not affect the comparison, e.g. annotations
+   * like `title`, `description`, etc.
+   *
+   * @param writerSchema       schema of the data being written
+   * @param readerSchema       schema of the data being read
+   * @param writerNamedSchemas named schemas which may be referred to by the writer schema
+   * @param readerNamedSchemas named schemas which may be referred to by the reader schema
+   * @return a list of incompatibilities between the schemas
+   */
   def compare(
     writerSchema: Schema,
     readerSchema: Schema,