Package com.arc_e_tect.gradle.doppelganger

Class ScanContractsTask

java.lang.Object
org.gradle.api.internal.AbstractTask
org.gradle.api.DefaultTask
com.arc_e_tect.gradle.doppelganger.ScanContractsTask
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, test, contract, and OpenAPI document content and is cheap to regenerate") public abstract class ScanContractsTask extends org.gradle.api.DefaultTask
Gradle task that, for every endpoint both declared in the configured OpenAPI documentation and implemented by a @RestController method, reports how many response codes its operation declares and how many contract tests exist for it - and, when DoppelgangerApiDetectorExtension.getIncludeResponseCoverage() is enabled, how many of those tests cover each declared response code.

Unlike DetectDoppelgangerApisTask, this task never fails the build on its own initiative - it is purely a reporting task, answering "how well is this API covered", not "is this API compliant".

Registered automatically by DoppelgangerApiDetectorPlugin under the name scanContracts.

  • 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
    ScanContractsTask()
    Creates the task.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    generate()
    Task action: scans the same candidate endpoints DetectDoppelgangerApisTask does, but reports response-code and contract-test coverage rather than a pass/fail verdict.
    abstract org.gradle.api.file.DirectoryProperty
    getContractsDir()
    Directory searched for Spring Cloud Contract DSL files when getUseSpringCloudContract() is true.
    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 DoppelgangerApiDetectorExtension.getExcludeFiles().
    abstract org.gradle.api.provider.ListProperty<String>
    getExcludePaths()
    Exclusion rule strings - see DoppelgangerApiDetectorExtension.getExcludePaths().
    abstract org.gradle.api.provider.ListProperty<String>
    getExcludeWellKnown()
    Bundled well-known exclusion set names - see DoppelgangerApiDetectorExtension.getExcludeWellKnown().
    abstract org.gradle.api.provider.Property<Boolean>
    getIncludeResponseCoverage()
    Whether to additionally compute, for every declared response code, how many contract tests cover it.
    abstract org.gradle.api.file.DirectoryProperty
    getOpenApiDir()
    Directory where OpenAPI descriptions are stored.
    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
    getResponseCoverageHistoryFile()
    File that the persisted response coverage history is read from and, when getUpdateResponseCoverageHistory() is true, written back to.
    String
    getResponseCoverageHistoryFilePath()
    The absolute path of getResponseCoverageHistoryFile(), tracked as a plain @Input value - see DetectDoppelgangerApisTask.getContractHistoryFilePath().
    abstract org.gradle.api.file.RegularFileProperty
    getRootDocument()
    The root OpenAPI document describing the API.
    abstract org.gradle.api.provider.Property<String>
    getSystemUnderTestVersion()
    Version of the system under test whose @RestController classes were scanned.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getTestDirs()
    Directories to search recursively for test classes.
    abstract org.gradle.api.provider.Property<Boolean>
    getTestDirsUserConfigured()
    See DetectDoppelgangerApisTask.getTestDirsUserConfigured().
    abstract org.gradle.api.provider.Property<Boolean>
    getTrackResponseCoverageHistory()
    Whether to persist, across builds, a history of response code coverage.
    abstract org.gradle.api.provider.Property<Boolean>
    getUpdateResponseCoverageHistory()
    Whether getResponseCoverageHistoryFile() is written back to disk after being updated with the current run's coverage.
    abstract org.gradle.api.provider.Property<Boolean>
    getUseOpenApiRequestValidator()
    Whether to treat Atlassian OpenAPI request validator usage as verification evidence.
    abstract org.gradle.api.provider.Property<Boolean>
    getUseRestDocs()
    Whether to treat Spring RestDocs test methods as verification evidence.
    abstract org.gradle.api.provider.Property<Boolean>
    getUseSpringCloudContract()
    Whether to treat Spring Cloud Contract DSL files as verification evidence.

    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

    • ScanContractsTask

      @Inject public ScanContractsTask()
      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.
      Returns:
      mutable file collection of controller source directories

    • getTestDirs

      @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.ConfigurableFileCollection getTestDirs()
      Directories to search recursively for test classes.
      Returns:
      mutable file collection of test source directories

    • getTestDirsUserConfigured

      @Input public abstract org.gradle.api.provider.Property<Boolean> getTestDirsUserConfigured()
      See DetectDoppelgangerApisTask.getTestDirsUserConfigured().
      Returns:
      mutable boolean property, true when getTestDirs() reflects the user's own configuration rather than only the plugin's default

    • getRootDocument

      @Optional @InputFiles @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 @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.DirectoryProperty getOpenApiDir()
      Directory where OpenAPI descriptions are stored.
      Returns:
      mutable directory property for the OpenAPI description directory

    • getContractsDir

      @Optional @InputFiles @PathSensitive(RELATIVE) public abstract org.gradle.api.file.DirectoryProperty getContractsDir()
      Directory searched for Spring Cloud Contract DSL files when getUseSpringCloudContract() is true.
      Returns:
      mutable directory property for the Spring Cloud Contract directory

    • getUseRestDocs

      @Input public abstract org.gradle.api.provider.Property<Boolean> getUseRestDocs()
      Whether to treat Spring RestDocs test methods as verification evidence.
      Returns:
      mutable boolean property controlling whether the Spring RestDocs source is enabled

    • getUseOpenApiRequestValidator

      @Input public abstract org.gradle.api.provider.Property<Boolean> getUseOpenApiRequestValidator()
      Whether to treat Atlassian OpenAPI request validator usage as verification evidence.
      Returns:
      mutable boolean property controlling whether the OpenAPI request validator source is enabled

    • getUseSpringCloudContract

      @Input public abstract org.gradle.api.provider.Property<Boolean> getUseSpringCloudContract()
      Whether to treat Spring Cloud Contract DSL files as verification evidence.
      Returns:
      mutable boolean property controlling whether the Spring Cloud Contract source is enabled

    • getIncludeResponseCoverage

      @Input public abstract org.gradle.api.provider.Property<Boolean> getIncludeResponseCoverage()
      Whether to additionally compute, for every declared response code, how many contract tests cover it. Defaults to false: the breakdown is not merely hidden when disabled, it is never computed.
      Returns:
      mutable boolean property controlling whether response coverage is computed

    • 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.
      Returns:
      mutable string property for the system-under-test version

    • getTrackResponseCoverageHistory

      @Input public abstract org.gradle.api.provider.Property<Boolean> getTrackResponseCoverageHistory()
      Whether to persist, across builds, a history of response code coverage. Only meaningful together with getIncludeResponseCoverage() - see generate()'s eager validation of that combination.
      Returns:
      mutable boolean property controlling whether response coverage history is tracked

    • getResponseCoverageHistoryFile

      @Internal public abstract org.gradle.api.file.RegularFileProperty getResponseCoverageHistoryFile()
      File that the persisted response coverage history is read from and, when getUpdateResponseCoverageHistory() is true, written back to. See DetectDoppelgangerApisTask.getContractHistoryFile() for why this is @Internal rather than tracked through Gradle's file-content-based up-to-date checking.
      Returns:
      mutable file property for the response coverage history file

    • getResponseCoverageHistoryFilePath

      @Input @Optional public String getResponseCoverageHistoryFilePath()
      The absolute path of getResponseCoverageHistoryFile(), tracked as a plain @Input value - see DetectDoppelgangerApisTask.getContractHistoryFilePath().
      Returns:
      the response coverage history file's absolute path, or null if unset

    • getUpdateResponseCoverageHistory

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

    • getExcludePaths

      @Input public abstract org.gradle.api.provider.ListProperty<String> getExcludePaths()
      Exclusion rule strings - see DoppelgangerApiDetectorExtension.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 DoppelgangerApiDetectorExtension.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 DoppelgangerApiDetectorExtension.getExcludeWellKnown().
      Returns:
      mutable list property of well-known exclusion set names

    • generate

      public void generate()
      Task action: scans the same candidate endpoints DetectDoppelgangerApisTask does, but reports response-code and contract-test coverage rather than a pass/fail verdict. Never fails the build on its own initiative. Bootstrapping-gap handling (a missing getRootDocument(), empty getControllerDirs(), etc.) follows the same "warn, don't fail" philosophy as DetectDoppelgangerApisTask.generate() - see that method's javadoc for the full rationale.

      Two DSL configurations are rejected eagerly: every verification source disabled at once (no test evidence could ever be gathered), getUseSpringCloudContract() enabled with getContractsDir() unconfigured, and - specific to this task - getTrackResponseCoverageHistory() enabled while getIncludeResponseCoverage() is disabled, since there would be no per-response-code data to persist.