Package com.arc_e_tect.gradle.doppelganger.scan

Class RestDocsScanner

java.lang.Object
com.arc_e_tect.gradle.doppelganger.scan.RestDocsScanner
All Implemented Interfaces:
ContractVerificationSource
public class RestDocsScanner extends Object implements ContractVerificationSource
ContractVerificationSource for Spring RestDocs, recognising three independent call-chain shapes for the same underlying convention - a request-builder call paired with a document(...) call somewhere in the same method body:
  • spring-restdocs-mockmvc: mockMvc.perform(get(...)/post(...)/put(...)/ delete(...)/patch(...)) together with .andDo(document(...)).
  • spring-restdocs-webtestclient: webTestClient.get()/post()/put()/ delete()/patch().uri(...).exchange()...consumeWith(document(...)) - the HTTP verb comes from the request-builder method and the path from the uri(...) call.
  • spring-restdocs-restassured: given(...).filter(document(...))... when().get(...)/post(...)/put(...)/delete(...)/patch(...) - the verb call directly scoped on a call named when.

Matches by simple method name only, the same way ControllerScanner matches mapping annotations by simple name, so this scanner needs neither Spring MVC Test, Spring RestDocs, nor REST Assured on its own classpath.

  • Constructor Summary

    Constructors
    Constructor
    Description
    RestDocsScanner()
    Creates a new RestDocsScanner that strips no base path from captured paths.
    RestDocsScanner(String basePathToStrip)
    Creates a new RestDocsScanner that strips basePathToStrip - typically resolved via OpenApiServerBasePath.resolve(java.io.File) - from the leading segments of every path it captures, when present.
    RestDocsScanner(String basePathToStrip, com.arc_e_tect.gradle.detector.core.scan.PropertyResolutionContext propertyResolutionContext)
    Creates a new RestDocsScanner that additionally resolves a request-builder call's path argument against propertyResolutionContext when it is a configured helper-method call or an @Value-annotated field, in addition to the literal/ literal-initialized-constant shapes LiteralPathResolver always resolves.

  • Method Summary

    Modifier and Type
    Method
    Description
    List<com.arc_e_tect.gradle.detector.core.model.Endpoint>
    scan(File rootDir)
    Scans rootDir recursively and returns every endpoint this source found verification evidence for.
    List<VerifiedContractTest>
    scanWithStatusCodes(File rootDir)
    Scans rootDir recursively, same as ContractVerificationSource.scan(File), but additionally reports the HTTP status code each piece of evidence was detected to assert, when a source is able to determine one.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • RestDocsScanner

      public RestDocsScanner()
      Creates a new RestDocsScanner that strips no base path from captured paths.

    • RestDocsScanner

      public RestDocsScanner(String basePathToStrip)
      Creates a new RestDocsScanner that strips basePathToStrip - typically resolved via OpenApiServerBasePath.resolve(java.io.File) - from the leading segments of every path it captures, when present. A REST Assured request built against a running server naturally includes this server-url path (e.g. a servlet context path) in the literal path it captures, even though neither the OpenAPI documentation nor the @RestController mapping it verifies ever declares it.
      Parameters:
      basePathToStrip - the base path to strip, e.g. "/user-account-service"; blank or null disables stripping

    • RestDocsScanner

      public RestDocsScanner(String basePathToStrip, com.arc_e_tect.gradle.detector.core.scan.PropertyResolutionContext propertyResolutionContext)
      Creates a new RestDocsScanner that additionally resolves a request-builder call's path argument against propertyResolutionContext when it is a configured helper-method call or an @Value-annotated field, in addition to the literal/ literal-initialized-constant shapes LiteralPathResolver always resolves.
      Parameters:
      basePathToStrip - see RestDocsScanner(String)
      propertyResolutionContext - out-of-band property knowledge; pass PropertyResolutionContext.empty() for none

  • Method Details

    • scan

      public List<com.arc_e_tect.gradle.detector.core.model.Endpoint> scan(File rootDir) throws IOException
      Scans rootDir recursively and returns every endpoint this source found verification evidence for.

      The returned Endpoint.declaringClass() and Endpoint.methodSignature() identify the test (or contract file) that supplied the evidence, not a production @RestController.

      Specified by:
      scan in interface ContractVerificationSource
      Parameters:
      rootDir - the directory to scan recursively; scanning a non-existent or non-directory path returns an empty list rather than failing
      Returns:
      possibly-empty list of verified endpoints, never null
      Throws:
      IOException - if a file under rootDir cannot be read

    • scanWithStatusCodes

      public List<VerifiedContractTest> scanWithStatusCodes(File rootDir) throws IOException
      Scans rootDir recursively, same as ContractVerificationSource.scan(File), but additionally reports the HTTP status code each piece of evidence was detected to assert, when a source is able to determine one.

      The default implementation delegates to ContractVerificationSource.scan(File) and reports every entry with no status code, so an implementation that has no meaningful way to detect one simply inherits correct, backward-compatible behavior without overriding anything.

      Specified by:
      scanWithStatusCodes in interface ContractVerificationSource
      Parameters:
      rootDir - the directory to scan recursively; scanning a non-existent or non-directory path returns an empty list rather than failing
      Returns:
      possibly-empty list of verified contract tests, never null
      Throws:
      IOException - if a file under rootDir cannot be read