mirror of
https://github.com/corda/corda.git
synced 2024-12-29 09:18:58 +00:00
1e12aebe0a
* 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.
80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
# API Scanner
|
|
|
|
Generates a text summary of Corda's public API that we can check for API-breaking changes.
|
|
|
|
```bash
|
|
$ gradlew generateApi
|
|
```
|
|
|
|
See [here](../../docs/source/api-index.rst) 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:
|
|
|
|
```gradle
|
|
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:
|
|
```gradle
|
|
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:
|
|
|
|
```gradle
|
|
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](../README.rst) for full installation instructions.
|