mirror of https://github.com/corda/corda.git synced 2024-12-20 13:33:12 +00:00

Chris Rankin 1e12aebe0a Gradle API Scanner plugin (#1669 )

* Skeleton plugin.
* Implement Gradle api-scanner plugin, and apply it.
* Generate API documentation for any jar without a classifier.
* Fix usage of smokeTests classifier.
* Tweak Gradle API usage.
* Upgrade to fast-classpath-scanner 2.7.0
* Include interfaces and more modifiers in the class description.
* Allow system classes to be supertypes and implemented interfaces.
* Make API Scanner plugin configuration tweakable via build.gradle.
* Add a miserable amount of unit testing.
* Sort methods and fields using their natural comparators. Way easier!
* Add README for api-scanner plugin.
* Add @OutputFiles to ScanApiTask.
* Rename ScanApiTask to ScanApi.
* Allow the ScanApi task to be disabled.
* WIP: Create a top-level GenerateApi task to collate the ScanApi output.
* Exclude package-private classes, as well as bridge/synthetic methods.
* Replace "End of Class" delimiter with '##'.
* Don't scan modules whose API is still "in flux".
* Include constructors in the API definitions.
* Finish implementation of GenerateApi task.
* Update README to include GenerateApi task.
* Filter out Kotlin's "internal" methods.
* Assign "fatjar" classifier to the fat jar artifact.
* Enhance README for GenerateApi.
* Explain effect of api-scanner plugin, and link to Corda's API strategy.
* Tweak README
* Exclude synthetic Kotlin classes by analysing @Metadata.
* Allow us to exclude some classes explicitly from the API.

2017-09-29 16:55:26 +01:00

3.1 KiB

Raw Blame History

API Scanner

Generates a text summary of Corda's public API that we can check for API-breaking changes.

$ gradlew generateApi

See here for Corda's public API strategy. We will need to apply this plugin to other modules in future Corda releases as those modules' APIs stabilise.

Basically, this plugin will document a module's public and protected classes/methods/fields, excluding those from our *.internal.* packgages, any synthetic methods, bridge methods, or methods identified as having Kotlin's internal scope. (Kotlin doesn't seem to have implemented internal scope for classes or fields yet as these are currently public inside the .class file.)

Usage

Include this line in the build.gradle file of every Corda module that exports public API:

apply plugin: 'net.corda.plugins.api-scanner'

This will create a Gradle task called scanApi which will analyse that module's Jar artifacts. More precisely, it will analyse all of the Jar artifacts that have not been assigned a Maven classifier, on the basis that these should be the module's main artifacts.

The scanApi task supports the following configuration options:

scanApi {
    // Make the classpath-scanning phase more verbose.
    verbose = {true|false}

    // Enable / disable the task within this module.
    enabled = {true|false}

    // Names of classes that should be excluded from the output.
    excludeClasses = [
        ...
    ]
}

All of the ScanApi tasks write their output files to their own $buildDir/api directory, where they are collated into a single output file by the GenerateApi task. The GenerateApi task is declared in the root project's build.gradle file:

task generateApi(type: net.corda.plugins.GenerateApi){
    baseName = "api-corda"
}

The final API file is written to $buildDir/api/$baseName-$project.version.txt

Sample Output

public interface net.corda.core.contracts.Attachment extends net.corda.core.contracts.NamedByHash
  public abstract void extractFile(String, java.io.OutputStream)
  @org.jetbrains.annotations.NotNull public abstract List getSigners()
  @org.jetbrains.annotations.NotNull public abstract java.io.InputStream open()
  @org.jetbrains.annotations.NotNull public abstract jar.JarInputStream openAsJAR()
##
public interface net.corda.core.contracts.AttachmentConstraint
  public abstract boolean isSatisfiedBy(net.corda.core.contracts.Attachment)
##
public final class net.corda.core.contracts.AttachmentResolutionException extends net.corda.core.flows.FlowException
  public <init>(net.corda.core.crypto.SecureHash)
  @org.jetbrains.annotations.NotNull public final net.corda.core.crypto.SecureHash getHash()
##

Notes

The GenerateApi task will collate the output of every ScanApi task found either in the same project, or in any of that project's subprojects. So it is theoretically possible also to collate the API output from subtrees of modules simply by defining a new GenerateApi task at the root of that subtree.

Plugin Installation

See here for full installation instructions.

3.1 KiB Raw Blame History