Package com.arc_e_tect.gradle.mirage

Class DetectMirageApisTask

java.lang.Object
org.gradle.api.internal.AbstractTask
org.gradle.api.DefaultTask
com.arc_e_tect.gradle.mirage.DetectMirageApisTask
All Implemented Interfaces:
Comparable<org.gradle.api.Task>, org.gradle.api.internal.DynamicObjectAware, org.gradle.api.internal.TaskInternal, org.gradle.api.Named, org.gradle.api.plugins.ExtensionAware, org.gradle.api.Task, org.gradle.util.Configurable<org.gradle.api.Task>
@DisableCachingByDefault(because="Report depends on source and OpenAPI document content and is cheap to regenerate") public abstract class DetectMirageApisTask extends org.gradle.api.DefaultTask
Gradle task that parses the configured OpenAPI documentation, compares the operations it describes against the endpoints exposed by scanned @RestController classes, and writes an AsciiDoc report of every operation that has no match - the "mirage APIs". When getScanMocks() is true, WireMock stub mapping files are additionally scanned for stub evidence, recorded into contract history/the report alongside the real implementation evidence above - but never counted as implementation evidence itself, so it never changes which endpoints are reported as mirage APIs.

Registered automatically by MirageApiDetectorPlugin under the name detectMirageApis.

  • Nested Class Summary

    Nested classes/interfaces inherited from interface org.gradle.api.Named

    org.gradle.api.Named.Namer

  • Field Summary

    Fields inherited from interface org.gradle.api.Task

    TASK_ACTION, TASK_CONSTRUCTOR_ARGS, TASK_DEPENDS_ON, TASK_DESCRIPTION, TASK_GROUP, TASK_NAME, TASK_OVERWRITE, TASK_TYPE

  • Constructor Summary

    Constructors
    Constructor
    Description
    DetectMirageApisTask()
    Creates the task.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    generate()
    Task action: loads the configured OpenAPI documentation, scans the configured controller directories - and, when getScanMocks() is true, additionally the configured WireMock stub directories - and writes the mirage API report.
    abstract org.gradle.api.provider.Property<String>
    getBasePath()
    The base path to strip from every path found under getStubDirs() before comparing it against the OpenAPI documentation, used only when getScanMocks() is true.
    abstract org.gradle.api.file.RegularFileProperty
    getContractHistoryFile()
    File that the persisted contract progress history is read from and, when getUpdateContractHistory() is true, written back to.
    String
    getContractHistoryFilePath()
    The absolute path of getContractHistoryFile(), tracked as a plain @Input value - not the file's content, which getContractHistoryFile() itself is deliberately excluded from up-to-date checking for.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getControllerDirs()
    Directories to search recursively for @RestController classes.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getExcludeFiles()
    External exclusion rule files - see MirageApiDetectorExtension.getExcludeFiles().
    abstract org.gradle.api.provider.ListProperty<String>
    getExcludePaths()
    Exclusion rule strings - see MirageApiDetectorExtension.getExcludePaths().
    abstract org.gradle.api.provider.ListProperty<String>
    getExcludeWellKnown()
    Bundled well-known exclusion set names - see MirageApiDetectorExtension.getExcludeWellKnown().
    abstract org.gradle.api.provider.Property<Boolean>
    getFailOnMirage()
    Whether the build should fail when mirage APIs are found.
    abstract org.gradle.api.file.DirectoryProperty
    getOpenApiDir()
    Directory where OpenAPI descriptions are stored, tracked so that changes to any document reachable from getRootDocument() invalidate the task's cached result.
    abstract org.gradle.api.file.DirectoryProperty
    getReportDir()
    Directory the AsciiDoc report is written to.
    abstract org.gradle.api.provider.Property<String>
    getReportFileName()
    Name of the generated AsciiDoc report file (without path).
    abstract org.gradle.api.file.RegularFileProperty
    getRootDocument()
    The root OpenAPI document describing the API.
    abstract org.gradle.api.provider.Property<Boolean>
    getScanMocks()
    Whether to additionally scan WireMock stub mapping files under getStubDirs() for stub evidence, recorded into contract history/the report alongside getControllerDirs()'s real implementation evidence.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getStubDirs()
    Directories to search recursively for WireMock stub mapping files, scanned for stub evidence when getScanMocks() is true.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getStubSourceDirs()
    Directories to search recursively for Java source files that create WireMock stubs programmatically at test run time, scanned for stub evidence when getScanMocks() is true - see MirageApiDetectorExtension.getStubSourceDirs().
    abstract org.gradle.api.provider.Property<String>
    getSystemUnderTestVersion()
    Version of the system under test whose @RestController classes were scanned, printed in the generated report as e.g.
    abstract org.gradle.api.provider.Property<Boolean>
    getTrackContractHistory()
    Whether to persist, across builds, a history of when each endpoint first reached each stage of its contract lifecycle - declared, implemented, verified.
    abstract org.gradle.api.provider.Property<Boolean>
    getUpdateContractHistory()
    Whether getContractHistoryFile() is written back to disk after being updated with the current run's endpoints.

    Methods inherited from class org.gradle.api.DefaultTask

    compareTo, configure, dependsOn, doFirst, doFirst, doFirst, doLast, doLast, doLast, finalizedBy, getActions, getAnt, getDependsOn, getDescription, getDestroyables, getDidWork, getEnabled, getExtensions, getFinalizedBy, getGroup, getInputs, getLocalState, getLogger, getLogging, getMustRunAfter, getName, getOutputs, getPath, getProject, getShouldRunAfter, getState, getTaskDependencies, getTemporaryDir, getTimeout, hasProperty, mustRunAfter, onlyIf, onlyIf, onlyIf, property, setActions, setDependsOn, setDescription, setDidWork, setEnabled, setFinalizedBy, setGroup, setMustRunAfter, setOnlyIf, setOnlyIf, setOnlyIf, setProperty, setShouldRunAfter, shouldRunAfter, usesService

    Methods inherited from class org.gradle.api.internal.AbstractTask

    acceptServiceReferences, appendParallelSafeAction, doNotTrackState, doNotTrackStateIf, getAsDynamicObject, getIdentityPath, getImpliesSubProjects, getLifecycleDependencies, getOnlyIf, getReasonNotToTrackState, getReasonsNotToTrackState, getReasonTaskIsIncompatibleWithConfigurationCache, getRequiredServices, getServices, getSharedResources, getStandardOutputCapture, getTaskActions, getTaskIdentity, getTemporaryDirFactory, hasTaskActions, injectIntoNewInstance, isCompatibleWithConfigurationCache, isEnabled, isHasCustomActions, notCompatibleWithConfigurationCache, prependParallelSafeAction, restoreOnlyIf, restoreTaskActions, setImpliesSubProjects

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.gradle.api.Task

    doNotTrackState, notCompatibleWithConfigurationCache

  • Constructor Details

    • DetectMirageApisTask

      @Inject public DetectMirageApisTask()
      Creates the task. Instantiated by Gradle infrastructure via Inject.

  • Method Details

    • getControllerDirs

      @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.ConfigurableFileCollection getControllerDirs()
      Directories to search recursively for @RestController classes. Always scanned, regardless of getScanMocks(): real implementation evidence is what determines which endpoints are reported as mirage APIs.
      Returns:
      mutable file collection of controller source directories

    • getScanMocks

      @Input public abstract org.gradle.api.provider.Property<Boolean> getScanMocks()
      Whether to additionally scan WireMock stub mapping files under getStubDirs() for stub evidence, recorded into contract history/the report alongside getControllerDirs()'s real implementation evidence. Stub evidence never counts as implementation evidence itself - it never changes which endpoints are reported as mirage APIs, only what stubbedAt the contract history/report show for them.
      Returns:
      mutable boolean property controlling whether stub scanning is additionally performed

    • getStubDirs

      @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.ConfigurableFileCollection getStubDirs()
      Directories to search recursively for WireMock stub mapping files, scanned for stub evidence when getScanMocks() is true. Not scanned otherwise.
      Returns:
      mutable file collection of WireMock stub directories

    • getStubSourceDirs

      @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.ConfigurableFileCollection getStubSourceDirs()
      Directories to search recursively for Java source files that create WireMock stubs programmatically at test run time, scanned for stub evidence when getScanMocks() is true - see MirageApiDetectorExtension.getStubSourceDirs(). Not scanned otherwise. Results are merged with getStubDirs()'s into the same stub evidence.
      Returns:
      mutable file collection of Java source directories to scan for WireMock's Java DSL

    • getBasePath

      @Input @Optional public abstract org.gradle.api.provider.Property<String> getBasePath()
      The base path to strip from every path found under getStubDirs() before comparing it against the OpenAPI documentation, used only when getScanMocks() is true. When unset, falls back to getRootDocument()'s own first servers entry's url at task-execution time - see MirageApiDetectorExtension.getBasePath() for the full explanation.
      Returns:
      mutable string property for the base path to strip from scanned stub paths

    • getRootDocument

      @Optional @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.RegularFileProperty getRootDocument()
      The root OpenAPI document describing the API.

      Validated as @InputFiles rather than @InputFile, and @Optional: unlike @InputFile, neither requires a value to be present nor the configured file to actually exist. A team bootstrapping a build script for a project whose OpenAPI documentation doesn't exist yet - or hasn't been configured yet - should get a report with a WARNING admonition explaining that from generate(), not an opaque Gradle input-validation failure before the task action ever runs.

      Returns:
      mutable file property for the root OpenAPI document

    • getOpenApiDir

      @Optional @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.DirectoryProperty getOpenApiDir()
      Directory where OpenAPI descriptions are stored, tracked so that changes to any document reachable from getRootDocument() invalidate the task's cached result.

      Validated as @InputFiles rather than @InputDirectory for the same reason as getRootDocument(): it defaults to that file's own parent directory, which does not exist either when the file itself does not.

      Returns:
      mutable directory property for the OpenAPI description directory

    • getFailOnMirage

      @Input public abstract org.gradle.api.provider.Property<Boolean> getFailOnMirage()
      Whether the build should fail when mirage APIs are found.
      Returns:
      mutable boolean property controlling whether the build fails on mirage APIs

    • getReportDir

      @OutputDirectory public abstract org.gradle.api.file.DirectoryProperty getReportDir()
      Directory the AsciiDoc report is written to.
      Returns:
      mutable directory property for the report output directory

    • getReportFileName

      @Input public abstract org.gradle.api.provider.Property<String> getReportFileName()
      Name of the generated AsciiDoc report file (without path).
      Returns:
      mutable string property for the report file name

    • getSystemUnderTestVersion

      @Input public abstract org.gradle.api.provider.Property<String> getSystemUnderTestVersion()
      Version of the system under test whose @RestController classes were scanned, printed in the generated report as e.g. System Under Test version: v1.0.0.
      Returns:
      mutable string property for the system-under-test version

    • getTrackContractHistory

      @Input public abstract org.gradle.api.provider.Property<Boolean> getTrackContractHistory()
      Whether to persist, across builds, a history of when each endpoint first reached each stage of its contract lifecycle - declared, implemented, verified.
      Returns:
      mutable boolean property controlling whether contract progress history is tracked

    • getContractHistoryFile

      @Internal public abstract org.gradle.api.file.RegularFileProperty getContractHistoryFile()
      File that the persisted contract progress history is read from and, when getUpdateContractHistory() is true, written back to. Deliberately not declared as an @InputFile/@OutputFile: the file legitimately may not exist yet (treated as an empty history, not an error) and is only conditionally written back, so it's read and written directly in generate() instead of through Gradle's file-content-based up-to-date checking. Its configured path - as opposed to the file's content - is still tracked as a plain input via getContractHistoryFilePath(), so that renaming or relocating it is itself enough to invalidate this task's up-to-date state.
      Returns:
      mutable file property for the contract history file

    • getContractHistoryFilePath

      @Input @Optional public String getContractHistoryFilePath()
      The absolute path of getContractHistoryFile(), tracked as a plain @Input value - not the file's content, which getContractHistoryFile() itself is deliberately excluded from up-to-date checking for. Without this, renaming or relocating contractHistoryFile in the build script - with no other configured input having changed - would leave this task UP-TO-DATE and silently skip writing history to the newly configured location.
      Returns:
      the contract history file's absolute path, or null if unset

    • getUpdateContractHistory

      @Input public abstract org.gradle.api.provider.Property<Boolean> getUpdateContractHistory()
      Whether getContractHistoryFile() is written back to disk after being updated with the current run's endpoints. Only consulted when getTrackContractHistory() is true; the history file is always read regardless.
      Returns:
      mutable boolean property controlling whether the contract history file is written back

    • getExcludePaths

      @Input public abstract org.gradle.api.provider.ListProperty<String> getExcludePaths()
      Exclusion rule strings - see MirageApiDetectorExtension.getExcludePaths().
      Returns:
      mutable list property of exclusion rule strings

    • getExcludeFiles

      @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.ConfigurableFileCollection getExcludeFiles()
      External exclusion rule files - see MirageApiDetectorExtension.getExcludeFiles().
      Returns:
      mutable file collection of exclusion rule files

    • getExcludeWellKnown

      @Input public abstract org.gradle.api.provider.ListProperty<String> getExcludeWellKnown()
      Bundled well-known exclusion set names - see MirageApiDetectorExtension.getExcludeWellKnown().
      Returns:
      mutable list property of well-known exclusion set names

    • generate

      public void generate()
      Task action: loads the configured OpenAPI documentation, scans the configured controller directories - and, when getScanMocks() is true, additionally the configured WireMock stub directories - and writes the mirage API report.

      A missing getRootDocument() or empty getControllerDirs() - e.g. a build script bootstrapped for a project whose OpenAPI documentation or @RestController classes don't exist yet - is not a build failure: it is recorded as a WARNING admonition in the generated report instead, and mirage API detection (and, deliberately, contract history advancement - see loadContractHistoryForDisplay()) is skipped for this run rather than computed from incomplete input and risking a false positive. A missing getStubDirs() entry (only consulted when getScanMocks() is true) only warns - it never suppresses detection, since stub evidence never determines which endpoints are reported as mirage APIs.

      The build still fails when a mirage API is genuinely found and getFailOnMirage() is true - the one failure condition this task ever raises on its own initiative, per this plugin's design: fail only on a real finding the DSL asked to fail on, never on merely incomplete input.