Class OpenApiCompatibilityChecker

java.lang.Object
com.kingsrook.qqq.middleware.javalin.tools.OpenApiCompatibilityChecker
public class OpenApiCompatibilityChecker extends Object
Structural comparison of two OpenAPI documents (as parsed YAML/JSON maps), reporting the changes that would break an existing client of the older one. Breaking (for a client built against OLD): - a path, or an operation (method) on a path, is removed; - a response status code of an operation is removed; - a parameter is removed, changes `in`, or becomes required (or a new required parameter is added); - a request body becomes required; - a component schema is removed; - in any schema: a property is removed, `type` or `format` changes, `$ref` changes, an enum value is removed, or a property becomes required. Not breaking: added paths, operations, optional parameters, properties, schemas, enum values and response codes; descriptions, summaries, tags and examples. Adding an enum value to a response can still surprise a strict client, so clients must treat unknown enum values as "other" (docs/UI-API-CLIENTS.md).

  • Constructor Details

    • OpenApiCompatibilityChecker

      public OpenApiCompatibilityChecker()

  • Method Details

    • parse

      public static Map<String,Object> parse(String yamlOrJson) throws com.fasterxml.jackson.core.JsonProcessingException
      Parse an OpenAPI YAML (or JSON) document into a map.
      Throws:
      com.fasterxml.jackson.core.JsonProcessingException

    • getInfoVersion

      public static String getInfoVersion(Map<String,Object> document)
      The info.version of a parsed document (or null).

    • isStructurallyEqual

      public static boolean isStructurallyEqual(Map<String,Object> a, Map<String,Object> b)
      Whether two documents are the same apart from documentation text (descriptions, summaries, examples) and info.

    • compareSemver

      public static int compareSemver(String a, String b)
      Compare semantic versions: negative, zero or positive as a invalid input: '<' b, a == b, a > b. Non-numeric parts sort as zero.

    • findBreakingChanges

      public static List<String> findBreakingChanges(Map<String,Object> oldDocument, Map<String,Object> newDocument)
      List the changes from OLD to NEW that would break a client of OLD.