Class UiApiContract

java.lang.Object

com.kingsrook.qqq.middleware.javalin.tools.UiApiContract

public class UiApiContract
extends Object

The UI API contract check, shared by core's UiApiContractTest and by the contract tests of modules and qbits that register extensions. Given the freshly generated document, the committed document and (optionally) the release baseline, it reports: - any difference between generated and committed (regenerate and commit); - any breaking change from baseline to committed (needs /qqq/v{N+1}); - a changed document whose info.version was not bumped past the baseline; - a MAJOR that does not match the URL version. See docs/UI-API-CHANGELOG.md.

Constructor Summary

Constructors

Constructor	Description
UiApiContract()

Method Summary

Modifier and Type	Method	Description
static List<String>	check(String generatedYaml, String committedYaml, String baselineYaml, int expectedMajor, String regenerateHint)	Run the contract checks.
static List<String>	check(String generatedYaml, String committedYaml, String baselineYaml, int expectedMajor, String regenerateHint, List<String> acceptedBreakingChanges)	Run the contract checks, accepting listed breaking-change reports.
static String	generateCoreYaml(AbstractMiddlewareVersion middlewareVersion)	The core document of a middleware version, as PublishAPI writes it (properties sorted, for stable diffs).
static String	generateExtensionYaml(AbstractMiddlewareVersion middlewareVersion, MiddlewareSpecExtension extension)	The document of one extension alone, as a module or qbit commits it.
static String	toYaml(OpenAPI openAPI)	Serialize an OpenAPI model the way the committed files are written.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

UiApiContract

public UiApiContract()

Method Details

generateCoreYaml

public static String generateCoreYaml(AbstractMiddlewareVersion middlewareVersion)
                               throws QException

The core document of a middleware version, as PublishAPI writes it (properties sorted, for stable diffs). Extensions are not included.

Throws:

QException

generateExtensionYaml

public static String generateExtensionYaml(AbstractMiddlewareVersion middlewareVersion,
 MiddlewareSpecExtension extension)
                                    throws QException

The document of one extension alone, as a module or qbit commits it.

Throws:

QException

toYaml

public static String toYaml(OpenAPI openAPI)

Serialize an OpenAPI model the way the committed files are written.

check

public static List<String> check(String generatedYaml,
 String committedYaml,
 String baselineYaml,
 int expectedMajor,
 String regenerateHint)

Run the contract checks. Returns the problems found (empty when the contract holds).

Parameters:

generatedYaml - the document generated from the code now

committedYaml - the committed document

baselineYaml - the document as of the last release (null to skip the compatibility and version checks)

expectedMajor - the URL major version (1 for /qqq/v1)

regenerateHint - how to regenerate, for the message

check

public static List<String> check(String generatedYaml,
 String committedYaml,
 String baselineYaml,
 int expectedMajor,
 String regenerateHint,
 List<String> acceptedBreakingChanges)

Run the contract checks, accepting listed breaking-change reports. An accepted change is a correction of the document to what the server always did (so no client could have relied on the old description); each entry is a substring of the reported change. Accepted changes are cleared when the baseline is refreshed. See docs/UI-API-CHANGELOG.md.