Package com.arc_e_tect.gradle.mirage

Class MirageApiDetectorExtension

java.lang.Object
com.arc_e_tect.gradle.mirage.MirageApiDetectorExtension
public abstract class MirageApiDetectorExtension extends Object
DSL extension for the Mirage API Detector Gradle plugin. 
 mirageApiDetector {
     controllerDirs.from('src/main/java')                                    // default
     rootDocument   = file('src/main/resources/openapi/openapi.yaml')       // required
     // openApiDir  = rootDocument.get().asFile.parentFile                  // default
     scanMocks      = false                                                  // default
     // stubDirs.from('src/test/resources/mappings')                       // default; used only when scanMocks = true
     // stubSourceDirs.from('src/test/java')                               // default (every source set except main); used only when scanMocks = true
     // basePath     = '/crm-service'   // optional; used only when scanMocks = true - see getBasePath()
     failOnMirage   = false                                                  // default
     reportDir      = layout.buildDirectory.dir('reports/mirage-api-detector') // default
     reportFileName = 'mirage-apis.adoc'                                     // default
     // systemUnderTestVersion = 'v1.0.0'          // optional; default: project.version
     trackContractHistory  = false                                           // default
     // contractHistoryFile = file('mirage-api-detector-contract-history.ndjson') // default
     updateContractHistory = trackContractHistory                            // default; see getUpdateContractHistory()

     // excludePaths.add('/actuator/health')                                 // default: empty
     // excludeFiles.from('mirage-exclusions.yaml')                          // default: empty
     // excludeWellKnown.add('spring-boot-actuator')                        // default: empty
 }

updateContractHistory can be overridden for the whole build from the command line, e.g. -PmirageApiDetector.updateContractHistory=true - see getUpdateContractHistory().

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    DEFAULT_CONTRACT_HISTORY_FILE_NAME
    Default name of the persisted contract progress history file.
    static final String
    DEFAULT_CONTROLLER_DIR
    Default relative path of the directory searched for @RestController classes.
    static final String
    DEFAULT_REPORT_FILE_NAME
    Default name of the generated AsciiDoc report file.
    static final String
    DEFAULT_STUB_DIR
    Default relative path of the directory searched for WireMock stub mapping files.
    static final String
    NAME
    Extension DSL block name, i.e.
    static final String
    UPDATE_CONTRACT_HISTORY_OVERRIDE_PROPERTY
    Name of the Gradle project property that overrides getUpdateContractHistory() from the command line for every project in the build, e.g.

  • Constructor Summary

    Constructors
    Constructor
    Description
    MirageApiDetectorExtension()
    For use by the Gradle-generated concrete subclass.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract org.gradle.api.provider.Property<String>
    getBasePath()
    The base path to strip from every path found under getStubDirs() and getStubSourceDirs() 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.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getControllerDirs()
    Directories to search recursively for @RestController classes, used to determine which OpenAPI operations are implemented - and thus which are reported as mirage APIs.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getExcludeFiles()
    One or more YAML files of exclusion rules, in the same format bundled well-known sets use:
    abstract org.gradle.api.provider.ListProperty<String>
    getExcludePaths()
    Exclusion rule strings, parsed by ExclusionRule.parse(String) - e.g.
    abstract org.gradle.api.provider.ListProperty<String>
    getExcludeWellKnown()
    Names of bundled, well-known exclusion sets to apply - e.g.
    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.
    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, alongside getControllerDirs()'s real implementation evidence.
    abstract org.gradle.api.file.ConfigurableFileCollection
    getStubDirs()
    Directories to search recursively for WireMock stub mapping files (*.json), 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 - e.g.
    abstract org.gradle.api.provider.Property<String>
    getSystemUnderTestVersion()
    Version of the system under test whose @RestController classes are 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 - keyed by a fingerprint of its HTTP verb and path so the history is shared correctly with Shadow and Doppelganger API Detector when they're pointed at the same getContractHistoryFile().
    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 java.lang.Object

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

  • Field Details

    • NAME

      public static final String NAME
      Extension DSL block name, i.e. the name used to register the extension with the project.
      See Also:

    • DEFAULT_CONTROLLER_DIR

      public static final String DEFAULT_CONTROLLER_DIR
      Default relative path of the directory searched for @RestController classes.
      See Also:

    • DEFAULT_STUB_DIR

      public static final String DEFAULT_STUB_DIR
      Default relative path of the directory searched for WireMock stub mapping files.
      See Also:

    • DEFAULT_REPORT_FILE_NAME

      public static final String DEFAULT_REPORT_FILE_NAME
      Default name of the generated AsciiDoc report file.
      See Also:

    • DEFAULT_CONTRACT_HISTORY_FILE_NAME

      public static final String DEFAULT_CONTRACT_HISTORY_FILE_NAME
      Default name of the persisted contract progress history file.
      See Also:

    • UPDATE_CONTRACT_HISTORY_OVERRIDE_PROPERTY

      public static final String UPDATE_CONTRACT_HISTORY_OVERRIDE_PROPERTY
      Name of the Gradle project property that overrides getUpdateContractHistory() from the command line for every project in the build, e.g. -PmirageApiDetector.updateContractHistory=true. Takes precedence over any project's own configured updateContractHistory value. The value is parsed as a boolean.
      See Also:

  • Constructor Details

    • MirageApiDetectorExtension

      public MirageApiDetectorExtension()
      For use by the Gradle-generated concrete subclass.

  • Method Details

    • getControllerDirs

      public abstract org.gradle.api.file.ConfigurableFileCollection getControllerDirs()
      Directories to search recursively for @RestController classes, used to determine which OpenAPI operations are implemented - and thus which are reported as mirage APIs. Always scanned, regardless of getScanMocks(). One or more directories may be configured. Defaults to "src/main/java".
      Returns:
      mutable file collection of controller source directories

    • getScanMocks

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

    • getStubDirs

      public abstract org.gradle.api.file.ConfigurableFileCollection getStubDirs()
      Directories to search recursively for WireMock stub mapping files (*.json), scanned for stub evidence when getScanMocks() is true. One or more directories may be configured. Defaults to "src/test/resources/mappings".
      Returns:
      mutable file collection of WireMock stub directories

    • getStubSourceDirs

      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 - e.g. via stubFor(get(urlEqualTo("/orders/1")) .willReturn(...)) - scanned for stub evidence when getScanMocks() is true. This is evidence getStubDirs() cannot see, since no *.json stub mapping file exists on disk for a stub registered this way. Results from both are merged into the same stub evidence.

      One or more directories may be configured. Left unconfigured (the default) while getScanMocks() is true, this defaults to the Java directories of every source set except main, when the java plugin is applied - not just the conventional test source set, but every additional test suite a project defines too (e.g. via the jvm-test-suite plugin's testing.suites, such as an integration- or system-test suite), since stub-creating code may live in any of them. Scanning them all by default avoids every project having to enumerate its own test suites explicitly. Since a project's full set of test suites can be large, set this explicitly to restrict the scan to only the directories that actually create stubs.

      Returns:
      mutable file collection of Java source directories to scan for WireMock's Java DSL

    • getBasePath

      public abstract org.gradle.api.provider.Property<String> getBasePath()
      The base path to strip from every path found under getStubDirs() and getStubSourceDirs() before comparing it against the OpenAPI documentation, used only when getScanMocks() is true. A WireMock stub mapping records the full request path a client actually sends - including whatever deployment-time context path the server runs under, e.g. /crm-service - while an OpenAPI-declared path never includes one. Left unconfigured (the default), this is instead read automatically from getRootDocument()'s own first servers entry's url, e.g. http://localhost:9011/crm-service yields /crm-service - set this explicitly only when the document either declares no servers entry or declares the wrong one for this purpose.
      Returns:
      mutable string property for the base path to strip from scanned stub paths

    • getRootDocument

      public abstract org.gradle.api.file.RegularFileProperty getRootDocument()
      The root OpenAPI document describing the API. Required: every other OpenAPI document is expected to be reachable from this one via $ref links relative to it.
      Returns:
      mutable file property for the root OpenAPI document

    • getOpenApiDir

      public abstract org.gradle.api.file.DirectoryProperty getOpenApiDir()
      Directory where OpenAPI descriptions are stored. Used only to determine which files the task should track as inputs for up-to-date checks; every document actually consulted is discovered by following the $ref links reachable from getRootDocument(). Defaults to the root document's own parent directory.
      Returns:
      mutable directory property for the OpenAPI description directory

    • getFailOnMirage

      public abstract org.gradle.api.provider.Property<Boolean> getFailOnMirage()
      Whether the build should fail when mirage APIs are found. The report is written either way. Defaults to false.
      Returns:
      mutable boolean property controlling whether the build fails on mirage APIs

    • getReportDir

      public abstract org.gradle.api.file.DirectoryProperty getReportDir()
      Directory the AsciiDoc report is written to. Defaults to build/reports/mirage-api-detector.
      Returns:
      mutable directory property for the report output directory

    • getReportFileName

      public abstract org.gradle.api.provider.Property<String> getReportFileName()
      Name of the generated AsciiDoc report file (without path). Defaults to "mirage-apis.adoc".
      Returns:
      mutable string property for the report file name

    • getSystemUnderTestVersion

      public abstract org.gradle.api.provider.Property<String> getSystemUnderTestVersion()
      Version of the system under test whose @RestController classes are scanned, printed in the generated report as e.g. System Under Test version: v1.0.0. Defaults to the project's own version (as set in the build file or a properties file); set this property to override that default, e.g. when the controllers scanned belong to a different artifact than the one being built.
      Returns:
      mutable string property for the system-under-test version

    • getTrackContractHistory

      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 - keyed by a fingerprint of its HTTP verb and path so the history is shared correctly with Shadow and Doppelganger API Detector when they're pointed at the same getContractHistoryFile(). Defaults to false.

      The history file configured via getContractHistoryFile() is always read when this property is true, regardless of getUpdateContractHistory().

      Returns:
      mutable boolean property controlling whether contract progress history is tracked

    • getContractHistoryFile

      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. Defaults to "mirage-api-detector-contract-history.ndjson" directly in the project directory - deliberately not under build/, since this file is meant to be committed to version control so the history survives across checkouts. Only consulted when getTrackContractHistory() is true.
      Returns:
      mutable file property for the contract history file

    • getUpdateContractHistory

      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. Defaults to the same value as getTrackContractHistory(). Only consulted when getTrackContractHistory() is true; the history file is always read regardless of this property's value, so a build with this set to false still reports against the up-to-date-in-memory history, it simply doesn't persist it.

      The "mirageApiDetector.updateContractHistory" project property, when set (e.g. -PmirageApiDetector.updateContractHistory=true), overrides this property for every project in the build regardless of what any project configures here - typically driven from a Gradle property set differently per branch in the CI pipeline, since the plugin itself has no notion of which branch is currently checked out.

      Returns:
      mutable boolean property controlling whether the contract history file is written back

    • getExcludePaths

      public abstract org.gradle.api.provider.ListProperty<String> getExcludePaths()
      Exclusion rule strings, parsed by ExclusionRule.parse(String) - e.g. "/actuator/health" (any verb) or "GET /actuator/**" (verb-restricted, Ant-style */** wildcards). A described endpoint matching any configured rule - from here, getExcludeFiles(), or getExcludeWellKnown() - is still a mirage API in fact (declared, unimplemented), but is reported under == Excluded Mirage APIs instead of == Mirage APIs: it never fails getFailOnMirage() and never reaches getContractHistoryFile(). Defaults to empty.
      Returns:
      mutable list property of exclusion rule strings

    • getExcludeFiles

      public abstract org.gradle.api.file.ConfigurableFileCollection getExcludeFiles()
      One or more YAML files of exclusion rules, in the same format bundled well-known sets use: 
       exclusions:
   - "/actuator/health"
   - "GET /actuator/**"
      Rules from every configured file are combined with getExcludePaths() and getExcludeWellKnown(). Lets a team check in its own reusable exclusion sets (e.g. an org-wide file shared across projects) alongside per-project ones. Defaults to empty.
      Returns:
      mutable file collection of exclusion rule files

    • getExcludeWellKnown

      public abstract org.gradle.api.provider.ListProperty<String> getExcludeWellKnown()
      Names of bundled, well-known exclusion sets to apply - e.g. "spring-boot-actuator" for Spring Boot Actuator's management endpoints, which are provided by the framework's own auto-configuration rather than a hand-written @RestController and so are structurally invisible to the controller scan even when documented and fully functional. Combined with getExcludePaths() and getExcludeFiles(). An unrecognised name fails the build. Defaults to empty.
      Returns:
      mutable list property of well-known exclusion set names