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 a set of implemented endpoints, and writes an AsciiDoc report of every operation that has no match - the "mirage APIs". The implemented-endpoint set is either the endpoints exposed by scanned @RestController classes (the default), or, when getScanMocks() is true, the requests stubbed by WireMock mapping files.

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 either the configured controller directories or WireMock stub directories (per getScanMocks()), writes the mirage API report, and - when getFailOnMirage() is true - fails the build if any mirage API was found.
    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.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getControllerDirs()
    Directories to search recursively for @RestController classes.
    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 determine implemented endpoints from WireMock stub mapping files under getStubDirs() instead of scanning @RestController classes.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getStubDirs()
    Directories to search recursively for WireMock stub mapping files, used to determine implemented endpoints when getScanMocks() is true.
    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. Not scanned when getScanMocks() is true.
      Returns:
      mutable file collection of controller source directories

    • getScanMocks

      @Input public abstract org.gradle.api.provider.Property<Boolean> getScanMocks()
      Whether to determine implemented endpoints from WireMock stub mapping files under getStubDirs() instead of scanning @RestController classes.
      Returns:
      mutable boolean property controlling whether stub-based scanning is used

    • getStubDirs

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

    • getRootDocument

      @InputFile @PathSensitive(RELATIVE) public abstract org.gradle.api.file.RegularFileProperty getRootDocument()
      The root OpenAPI document describing the API.
      Returns:
      mutable file property for the root OpenAPI document

    • getOpenApiDir

      @Optional @InputDirectory @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.
      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 up-to-date checking.
      Returns:
      mutable file property for the contract history file

    • 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

    • generate

      public void generate()
      Task action: loads the configured OpenAPI documentation, scans either the configured controller directories or WireMock stub directories (per getScanMocks()), writes the mirage API report, and - when getFailOnMirage() is true - fails the build if any mirage API was found.