From a162165a0fea376c40f5a227181142fef01bcfc8 Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Wed, 31 Jul 2024 15:46:40 +0200 Subject: [PATCH] Bundle Javadoc with Antora documentation site. Closes #872 --- .gitignore | 1 - pom.xml | 27 ++++++++++++ spring-vault-distribution/package.json | 10 +++++ spring-vault-distribution/pom.xml | 27 +++++++----- src/main/antora/antora-playbook.yml | 18 +++----- src/main/antora/antora.yml | 5 +++ src/main/antora/modules/ROOT/nav.adoc | 3 ++ .../ROOT/pages/vault/authentication.adoc | 8 ++-- .../ROOT/pages/vault/client-support.adoc | 4 +- .../ROOT/pages/vault/imperative-template.adoc | 42 ++++++++++-------- .../ROOT/pages/vault/propertysource.adoc | 6 +-- .../ROOT/pages/vault/reactive-template.adoc | 43 ++++++++++--------- .../ROOT/pages/vault/vault-repositories.adoc | 2 +- .../pages/vault/vault-secret-engines.adoc | 28 ++++++------ .../resources/antora-resources/antora.yml | 1 - 15 files changed, 138 insertions(+), 87 deletions(-) create mode 100644 spring-vault-distribution/package.json diff --git a/.gitignore b/.gitignore index ca321fbc..aefb4f4f 100644 --- a/.gitignore +++ b/.gitignore @@ -24,5 +24,4 @@ work/ node node_modules -package.json package-lock.json diff --git a/pom.xml b/pom.xml index 1364fa3a..3fed13f0 100644 --- a/pom.xml +++ b/pom.xml @@ -18,6 +18,7 @@ + 1.0.0-alpha.4 0.0.3 3.25.1 2.21.46 @@ -996,6 +997,32 @@ + + + antora + + + true + true + true + true + true + + + + + + + org.jetbrains.kotlin + kotlin-maven-plugin + false + + true + + + + + diff --git a/spring-vault-distribution/package.json b/spring-vault-distribution/package.json new file mode 100644 index 00000000..057a40fe --- /dev/null +++ b/spring-vault-distribution/package.json @@ -0,0 +1,10 @@ +{ + "dependencies": { + "antora": "3.2.0-alpha.6", + "@antora/atlas-extension": "1.0.0-alpha.2", + "@antora/collector-extension": "1.0.0-alpha.7", + "@asciidoctor/tabs": "1.0.0-beta.6", + "@springio/antora-extensions": "1.13.0", + "@springio/asciidoctor-extensions": "1.0.0-alpha.11" + } +} diff --git a/spring-vault-distribution/pom.xml b/spring-vault-distribution/pom.xml index 4b11a0cd..c9328602 100644 --- a/spring-vault-distribution/pom.xml +++ b/spring-vault-distribution/pom.xml @@ -124,24 +124,17 @@ - io.spring.maven.antora + org.antora antora-maven-plugin - ${antora.version} + ${maven.antora-version} true + ${project.basedir}/../src/main/antora/antora-playbook.yml - ${project.basedir}/../src/main/antora/antora-playbook.yml - - @antora/atlas-extension@1.0.0-alpha.1 - @antora/collector-extension@1.0.0-alpha.3 - @asciidoctor/tabs@1.0.0-beta.3 - @springio/antora-extensions@1.8.0 - @springio/asciidoctor-extensions@1.0.0-alpha.9 - @@ -245,6 +238,20 @@ + + copy-javadoc + package + + + + + + + + + run + + diff --git a/src/main/antora/antora-playbook.yml b/src/main/antora/antora-playbook.yml index 816afc29..1cf159f4 100644 --- a/src/main/antora/antora-playbook.yml +++ b/src/main/antora/antora-playbook.yml @@ -1,13 +1,7 @@ # The purpose of this Antora playbook is to build the docs in the current branch. antora: extensions: - - '@springio/antora-extensions/partial-build-extension' - - '@springio/antora-extensions/static-page-extension' - - require: '@springio/antora-extensions/latest-version-extension' - - require: '@springio/antora-extensions/inject-collector-cache-config-extension' - - '@antora/collector-extension' - - '@antora/atlas-extension' - - require: '@springio/antora-extensions/root-component-extension' + - require: '@springio/antora-extensions' root_component_name: 'vault' site: title: Spring Vault @@ -28,13 +22,15 @@ asciidoc: extensions: - '@asciidoctor/tabs' - '@springio/asciidoctor-extensions' + - '@springio/asciidoctor-extensions/javadoc-extension' + sourcemap: true urls: latest_version_segment: '' -ui: - bundle: - url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.4.7/ui-bundle.zip - snapshot: true runtime: log: failure_level: warn format: pretty +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.4.16/ui-bundle.zip + snapshot: true diff --git a/src/main/antora/antora.yml b/src/main/antora/antora.yml index cc61502b..747e3797 100644 --- a/src/main/antora/antora.yml +++ b/src/main/antora/antora.yml @@ -10,3 +10,8 @@ ext: local: true scan: dir: spring-vault-distribution/target/classes/ + - run: + command: ./mvnw package -Pdistribute + local: true + scan: + dir: target/antora diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc index 873c97a0..7d6822a0 100644 --- a/src/main/antora/modules/ROOT/nav.adoc +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -12,3 +12,6 @@ ** xref:vault/client-support.adoc[] ** xref:vault/authentication.adoc[] ** xref:vault/spring-security.adoc[] + + +* xref:attachment$api/java/index.html[Javadoc,role=link-external,window=_blank] diff --git a/src/main/antora/modules/ROOT/pages/vault/authentication.adoc b/src/main/antora/modules/ROOT/pages/vault/authentication.adoc index 03f096d9..87bee6dd 100644 --- a/src/main/antora/modules/ROOT/pages/vault/authentication.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/authentication.adoc @@ -939,14 +939,14 @@ VaultToken token = executor.login(); Vault's tokens can be associated with a time to live. Tokens obtained by an authentication method are intended to be used as long as the session is active and should not expire while the application is active. -Spring Vault provides with {self-docs-root}api/org/springframework/vault/authentication/LifecycleAwareSessionManager.html[`LifecycleAwareSessionManager`] a session manager that can renew the token until it reaches its terminal TTL to then perform another login to obtain the next token which is associated with the session. +Spring Vault provides with javadoc:org.springframework.vault.authentication.LifecycleAwareSessionManager[] a session manager that can renew the token until it reaches its terminal TTL to then perform another login to obtain the next token which is associated with the session. Depending on the authentication method, a login can create two kinds of tokens: -* {self-docs-root}api/org/springframework/vault/support/VaultToken.html[`VaultToken`]: Generic token encapsulating the actual token. -* {self-docs-root}api/org/springframework/vault/authentication/LoginToken.html[`LoginToken`]: Token associated with renewability/TTL. +* javadoc:org.springframework.vault.support.VaultToken[]: Generic token encapsulating the actual token. +* javadoc:org.springframework.vault.authentication.LoginToken[]: Token associated with renewability/TTL. -Authentication methods such as {self-docs-root}api/org/springframework/vault/authentication/TokenAuthentication.html[`TokenAuthentication`] just create a `VaultToken` which does not carry any renewability/TTL details. `LifecycleAwareSessionManager` will run a self-lookup on the token to retrieve renewability and TTL from Vault. +Authentication methods such as javadoc:org.springframework.vault.authentication.TokenAuthentication[] just create a `VaultToken` which does not carry any renewability/TTL details. javadoc:org.springframework.vault.authentication.LifecycleAwareSessionManager[] will run a self-lookup on the token to retrieve renewability and TTL from Vault. `VaultToken` are renewed periodically if self-lookup is enabled. Note that `VaultToken` are never revoked, only `LoginToken` are revoked. Authentication methods creating `LoginToken` directly (all login-based authentication methods) already provide all necessary details to setup token renewal. Tokens obtained from a login are revoked by `LifecycleAwareSessionManager` if the session manager is shut down. diff --git a/src/main/antora/modules/ROOT/pages/vault/client-support.adoc b/src/main/antora/modules/ROOT/pages/vault/client-support.adoc index 93d2bb20..18d0a63d 100644 --- a/src/main/antora/modules/ROOT/pages/vault/client-support.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/client-support.adoc @@ -98,7 +98,7 @@ NOTE: Apache HttpClient's https://hc.apache.org/httpcomponents-client-5.2.x/logg [[vault.client-ssl]] == Vault Client SSL configuration -SSL can be configured using `SslConfiguration` by setting various properties. +SSL can be configured using javadoc:org.springframework.vault.support.SslConfiguration[] by setting various properties. You can set either `javax.net.ssl.trustStore` to configure JVM-wide SSL settings or configure `SslConfiguration` to set SSL settings only for Spring Vault. @@ -128,7 +128,7 @@ SslConfiguration.forKeyStore(new FileSystemResource("keystore.jks"), <4> <4> Configuring only key store settings with providing a key-configuration. ==== -Please note that providing `SslConfiguration` can be only applied when either Apache Http Components or the OkHttp client is on your class-path. +Please note that providing javadoc:org.springframework.vault.support.SslConfiguration[] can be only applied when either Apache Http Components or the OkHttp client is on your class-path. The SSL configuration supports also PEM-encoded certificates as alternative to a Java Key Store. diff --git a/src/main/antora/modules/ROOT/pages/vault/imperative-template.adoc b/src/main/antora/modules/ROOT/pages/vault/imperative-template.adoc index d8a81260..8b1fffc7 100644 --- a/src/main/antora/modules/ROOT/pages/vault/imperative-template.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/imperative-template.adoc @@ -1,19 +1,20 @@ [[vault.core.template]] = Introduction to VaultTemplate -The class `VaultTemplate`, located in the package `org.springframework.vault.core`, +The class javadoc:org.springframework.vault.core.VaultTemplate[], located in the package `org.springframework.vault.core`, is the central class of the Spring's Vault support providing a rich feature set to interact with Vault. The template offers convenience operations to read, write and delete data in Vault and provides a mapping between your domain objects and Vault data. -NOTE: Once configured, `VaultTemplate` is thread-safe and can be reused across +NOTE: Once configured, javadoc:org.springframework.vault.core.VaultTemplate[] is thread-safe and can be reused across multiple instances. The mapping between Vault documents and domain classes is done by delegating to `RestTemplate`. Spring Web support provides the mapping infrastructure. -The `VaultTemplate` class implements the interface `VaultOperations`. -In as much as possible, the methods on `VaultOperations` are named after methods +The javadoc:org.springframework.vault.core.VaultTemplate[] class implements the interface +javadoc:org.springframework.vault.core.VaultOperations[]. +In as much as possible, the methods on javadoc:org.springframework.vault.core.VaultOperations[] are named after methods available on the Vault API to make the API familiar to existing Vault developers who are used to the API and CLI. For example, you will find methods such as "write", "delete", "read", and "revoke". @@ -22,8 +23,8 @@ the use of the Vault API and `VaultOperations`. A major difference in between the two APIs is that `VaultOperations` can be passed domain objects instead of JSON Key-Value pairs. -NOTE: The preferred way to reference the operations on `VaultTemplate` instance -is via its interface `VaultOperations`. +NOTE: The preferred way to reference the operations on javadoc:org.springframework.vault.core.VaultTemplate[] instance +is via its interface javadoc:org.springframework.vault.core.VaultOperations[]. While there are many convenience methods on `VaultTemplate` to help you easily perform common tasks if you should need to access the Vault API directly to access @@ -37,7 +38,8 @@ Now let's look at a examples of how to work with Vault in the context of the Spr [[vault.core.template.beans]] == Registering and configuring Spring Vault beans -Using Spring Vault does not require a Spring Context. However, instances of `VaultTemplate` and `SessionManager` registered inside a managed context will participate +Using Spring Vault does not require a Spring Context. However, instances of `VaultTemplate` and +javadoc:org.springframework.vault.authentication.SessionManager[] registered inside a managed context will participate in {spring-framework-docs}core.html#beans-factory-nature[lifecycle events] provided by the Spring IoC container. This is useful to dispose active Vault sessions upon application shutdown. You also benefit from reusing the same `VaultTemplate` @@ -45,11 +47,11 @@ instance across your application. Spring Vault comes with a supporting configuration class that provides bean definitions for use inside a Spring context. Application configuration -classes typically extend from `AbstractVaultConfiguration` and are required to +classes typically extend from javadoc:org.springframework.vault.config.AbstractVaultConfiguration[] and are required to provide additional details that are environment specific. -Extending from `AbstractVaultConfiguration` requires to implement -` VaultEndpoint vaultEndpoint()` and `ClientAuthentication clientAuthentication()` +Extending from javadoc:org.springframework.vault.config.AbstractVaultConfiguration[] requires to implement +`VaultEndpoint vaultEndpoint()` and `ClientAuthentication clientAuthentication()` methods. .Registering Spring Vault objects using Java based bean metadata @@ -78,8 +80,8 @@ public class AppConfig extends AbstractVaultConfiguration { } } ---- -<1> Create a new `VaultEndpoint` that points by default to `\https://localhost:8200`. -<2> This sample uses `TokenAuthentication` to get started quickly. +<1> Create a new javadoc:org.springframework.vault.client.VaultEndpoint[] that points by default to `\https://localhost:8200`. +<2> This sample uses javadoc:org.springframework.vault.authentication.TokenAuthentication[] to get started quickly. See <> for details on supported authentication methods. ==== @@ -111,14 +113,14 @@ public class AppConfig extends AbstractVaultConfiguration { } } ---- -<1> `VaultEndpoint` can be constructed using various factory methods such as +<1> javadoc:org.springframework.vault.client.VaultEndpoint[] can be constructed using various factory methods such as `from(URI uri)` or `VaultEndpoint.create(String host, int port)`. <2> Dependencies for `ClientAuthentication` methods can be obtained either from `AbstractVaultConfiguration` or provided by your configuration. ==== NOTE: Creating a custom configuration class might be cumbersome in some cases. -Take a look at `EnvironmentVaultConfiguration` that allows configuration by using +Take a look at javadoc:org.springframework.vault.config.EnvironmentVaultConfiguration[] that allows configuration by using properties from existing property sources and Spring's `Environment`. Read more in <>. @@ -132,9 +134,9 @@ must be reused throughout a session. This aspect is handled by a `SessionManager` implementation. A `SessionManager` decides how often it obtains a token, about revocation and renewal. Spring Vault comes with two implementations: -* `SimpleSessionManager`: Just obtains tokens from the supplied +* javadoc:org.springframework.vault.authentication.SimpleSessionManager[]: Just obtains tokens from the supplied `ClientAuthentication` without refresh and revocation -* `LifecycleAwareSessionManager`: This `SessionManager` schedules token +* javadoc:org.springframework.vault.authentication.LifecycleAwareSessionManager[]: This `SessionManager` schedules token renewal if a token is renewable and revoke a login token on disposal. Renewal is scheduled with an `AsyncTaskExecutor`. `LifecycleAwareSessionManager` is configured by default if using `AbstractVaultConfiguration`. @@ -142,8 +144,10 @@ is configured by default if using `AbstractVaultConfiguration`. [[vault.core.environment-vault-configuration]] == Using `EnvironmentVaultConfiguration` -Spring Vault includes `EnvironmentVaultConfiguration` configure the Vault client from Spring's `Environment` and a set of predefined -property keys. `EnvironmentVaultConfiguration` supports frequently applied configurations. Other configurations are supported by deriving from the most appropriate configuration class. Include `EnvironmentVaultConfiguration` with `@Import(EnvironmentVaultConfiguration.class)` to existing +Spring Vault includes javadoc:org.springframework.vault.config.EnvironmentVaultConfiguration[] configure the Vault client from Spring's `Environment` and a set of predefined +property keys. +javadoc:org.springframework.vault.config.EnvironmentVaultConfiguration[] supports frequently applied configurations. Other configurations are supported by deriving from the most appropriate configuration class. +Include javadoc:org.springframework.vault.config.EnvironmentVaultConfiguration[] with `@Import(EnvironmentVaultConfiguration.class)` to existing Java-based configuration classes and supply configuration properties through any of Spring's ``PropertySource``s. .Using EnvironmentVaultConfiguration with a property file @@ -238,7 +242,7 @@ One common design feature of all Spring template classes is that all functionali This helps ensure that exceptions and any resource management that maybe required are performed consistency. While this was of much greater need in the case of JDBC and JMS than with Vault, it still offers a single spot for access and logging to occur. As such, using the execute callback is the preferred way to access the Vault API -to perform uncommon operations that we've not exposed as methods on `VaultTemplate`. +to perform uncommon operations that we've not exposed as methods on javadoc:org.springframework.vault.core.VaultTemplate[]. Here is a list of execute callback methods. diff --git a/src/main/antora/modules/ROOT/pages/vault/propertysource.adoc b/src/main/antora/modules/ROOT/pages/vault/propertysource.adoc index 72348ab4..57a0bb76 100644 --- a/src/main/antora/modules/ROOT/pages/vault/propertysource.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/propertysource.adoc @@ -5,14 +5,14 @@ Vault can be used in many different ways. One specific use-case is using Vault to store encrypted properties. Spring Vault supports Vault as property source to obtain configuration properties using Spring's {spring-framework-docs}core.html#beans-property-source-abstraction[PropertySource abstraction]. -NOTE: You can reference properties stored inside Vault in other property sources or use value injection with `@Value(…)`. Special attention is required when bootstrapping beans that require data stored inside of Vault. A `VaultPropertySource` must be initialized at that time to retrieve properties from Vault. +NOTE: You can reference properties stored inside Vault in other property sources or use value injection with `@Value(…)`. Special attention is required when bootstrapping beans that require data stored inside of Vault. A javadoc:org.springframework.vault.core.env.VaultPropertySource[] must be initialized at that time to retrieve properties from Vault. NOTE: Spring Boot/Spring Cloud users can benefit from https://github.com/spring-cloud/spring-cloud-vault-config[Spring Cloud Vault]'s configuration integration that initializes various property sources during application startup. == Registering `VaultPropertySource` -Spring Vault provides a `VaultPropertySource` to be used with Vault to obtain +Spring Vault provides a javadoc:org.springframework.vault.core.env.VaultPropertySource[] to be used with Vault to obtain properties. It uses the nested `data` element to expose properties stored and encrypted in Vault. @@ -25,7 +25,7 @@ sources.addFirst(new VaultPropertySource(vaultTemplate, "secret/my-application") ---- ==== -In the code above, `VaultPropertySource` has been added with highest precedence +In the code above, javadoc:org.springframework.vault.core.env.VaultPropertySource[] has been added with highest precedence in the search. If it contains a ´foo` property, it will be detected and returned ahead of any `foo` property in any other `PropertySource`. `MutablePropertySources` exposes a number of methods that allow for precise diff --git a/src/main/antora/modules/ROOT/pages/vault/reactive-template.adoc b/src/main/antora/modules/ROOT/pages/vault/reactive-template.adoc index 7768e890..b9db2d88 100644 --- a/src/main/antora/modules/ROOT/pages/vault/reactive-template.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/reactive-template.adoc @@ -20,58 +20,59 @@ too slow the data repository can also slow down or stop completely until network Spring Vault's reactive client support is built on top of <> and Spring's functional `WebClient` via Reactor Netty or Jetty, which feature both a fully non-blocking, event-driven HTTP client. -It exposes `VaultTokenSupplier` as supplier of `VaultToken` to authenticate HTTP requests -and `ReactiveVaultOperations` as the primary entry point. The core configuration of +It exposes javadoc:org.springframework.vault.authentication.VaultTokenSupplier[] as supplier of javadoc:org.springframework.vault.support.VaultToken[] to authenticate HTTP requests +and javadoc:org.springframework.vault.core.ReactiveVaultOperations[] as the primary entry point. +The core configuration of `VaultEndpoint`, `ClientOptions` and <> are reused across the various client implementation. -The class `ReactiveVaultTemplate`, located in the package `org.springframework.vault.core`, +The class javadoc:org.springframework.vault.core.ReactiveVaultTemplate[], located in the package `org.springframework.vault.core`, is the central class of the Spring's reactive Vault support providing a rich feature set to interact with Vault. The template offers convenience operations to read, write and delete data in Vault and provides a mapping between your domain objects and Vault data. -NOTE: Once configured, `ReactiveVaultTemplate` is thread-safe and can be reused across +NOTE: Once configured, javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] is thread-safe and can be reused across multiple instances. The mapping between Vault documents and domain classes is done by delegating to `WebClient` and its codecs. -The `ReactiveVaultTemplate` class implements the interface `ReactiveVaultOperations`. -In as much as possible, the methods on `ReactiveVaultOperations` are named after methods +The javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] class implements the interface javadoc:org.springframework.vault.core.ReactiveVaultOperations[]. +In as much as possible, the methods on javadoc:org.springframework.vault.core.ReactiveVaultOperations[] are named after methods available on the Vault API to make the API familiar to existing Vault developers who are used to the API and CLI. For example, you will find methods such as "write", "delete", and "read". The design goal was to make it as easy as possible to transition between -the use of the Vault API and `ReactiveVaultOperations`. A major difference in between -the two APIs is that `ReactiveVaultOperations` can be passed domain objects instead of +the use of the Vault API and javadoc:org.springframework.vault.core.ReactiveVaultOperations[]. A major difference in between +the two APIs is that javadoc:org.springframework.vault.core.ReactiveVaultOperations[] can be passed domain objects instead of JSON Key-Value pairs. -NOTE: The preferred way to reference the operations on `ReactiveVaultTemplate` instance -is via its interface `ReactiveVaultOperations`. +NOTE: The preferred way to reference the operations on javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] instance +is via its interface javadoc:org.springframework.vault.core.ReactiveVaultOperations[]. -Functionality not explicitly exposed by the `ReactiveVaultTemplate` you can use one of +Functionality not explicitly exposed by the javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] you can use one of several execute callback methods to access underlying APIs. The execute callbacks will give you a reference to a `WebClient` object. Please see the section <> for more information. -Now let's look at a examples of how to work with Vault in the context of the Spring container. +Now let's look at examples of how to work with Vault in the context of the Spring container. [[vault.core.reactive.template.beans]] == Registering and configuring Spring Vault beans Using Spring Vault does not require a Spring Context. However, instances of -`ReactiveVaultTemplate` and `VaultTokenSupplier` registered inside a managed context will participate +javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] and `VaultTokenSupplier` registered inside a managed context will participate in {spring-framework-docs}core.html#beans-factory-nature[lifecycle events] provided by the Spring IoC container. This is useful to dispose active Vault sessions upon -application shutdown. You also benefit from reusing the same `ReactiveVaultTemplate` +application shutdown. You also benefit from reusing the same javadoc:org.springframework.vault.core.ReactiveVaultTemplate[] instance across your application. Spring Vault comes with a supporting configuration class that provides bean definitions for use inside a Spring context. Application configuration -classes typically extend from `AbstractVaultConfiguration` and are required to +classes typically extend from javadoc:org.springframework.vault.config.AbstractVaultConfiguration[] and are required to provide additional details that are environment specific. -Extending from `AbstractVaultConfiguration` requires to implement +Extending from javadoc:org.springframework.vault.config.AbstractVaultConfiguration[] requires to implement ` VaultEndpoint vaultEndpoint()` and `ClientAuthentication clientAuthentication()` methods. @@ -101,8 +102,8 @@ public class AppConfig extends AbstractReactiveVaultConfiguration { } } ---- -<1> Create a new `VaultEndpoint` that points by default to `\https://localhost:8200`. -<2> This sample uses `TokenAuthentication` to get started quickly. +<1> Create a new javadoc:org.springframework.vault.client.VaultEndpoint[] that points by default to `\https://localhost:8200`. +<2> This sample uses javadoc:org.springframework.vault.authentication.TokenAuthentication[] to get started quickly. See <> for details on supported authentication methods. ==== @@ -115,8 +116,8 @@ The reactive client requires a non-blocking token supplier whose contract is def in `VaultTokenSupplier`. Tokens can be static or obtained through a <>. Vault login should not occur on each authenticated Vault interaction but -the session token should be kept across a session. This aspect is handled by a -session manager implementing `ReactiveSessionManager`, such as `ReactiveLifecycleAwareSessionManager`. +the session token should be kept across a session. +This aspect is handled by a session manager implementing javadoc:org.springframework.vault.authentication.ReactiveSessionManager[], such as javadoc:org.springframework.vault.authentication.ReactiveLifecycleAwareSessionManager[]. [[vault.core.reactive.executioncallback]] == Execution callbacks @@ -127,7 +128,7 @@ that exceptions and any resource management that maybe required are performed consistency. While this was of much greater need in the case of JDBC and JMS than with Vault, it still offers a single spot for access and logging to occur. As such, using the execute callback is the preferred way to access the Vault API -to perform uncommon operations that we've not exposed as methods on `ReactiveVaultTemplate`. +to perform uncommon operations that we've not exposed as methods on javadoc:org.springframework.vault.core.ReactiveVaultTemplate[]. Here is a list of execute callback methods. diff --git a/src/main/antora/modules/ROOT/pages/vault/vault-repositories.adoc b/src/main/antora/modules/ROOT/pages/vault/vault-repositories.adoc index a519f660..24353a2c 100644 --- a/src/main/antora/modules/ROOT/pages/vault/vault-repositories.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/vault-repositories.adoc @@ -1,7 +1,7 @@ [[vault.repositories]] = Vault Repositories -Working with `VaultTemplate` and responses mapped to Java classes allows basic data operations like read, write and delete. +Working with javadoc:org.springframework.vault.core.VaultTemplate[] and responses mapped to Java classes allows basic data operations like read, write and delete. Vault repositories apply Spring Data's repository concept on top of Vault. A Vault repository exposes basic CRUD functionality and supports query derivation with predicates constraining the identifier property, paging and sorting. Vault repositories use the key/value secrets engine functionality to persist and query data. diff --git a/src/main/antora/modules/ROOT/pages/vault/vault-secret-engines.adoc b/src/main/antora/modules/ROOT/pages/vault/vault-secret-engines.adoc index ae633b4b..4818492d 100644 --- a/src/main/antora/modules/ROOT/pages/vault/vault-secret-engines.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/vault-secret-engines.adoc @@ -25,7 +25,7 @@ The benefits of non-versioned kv is a reduced storage size for each key, since n Additionally, requests going to a backend configured this way are more performant because there are fewer storage calls and no locking for any given request. Spring Vault ships with a dedicated Key-Value API to encapsulate differences between the individual Key-Value API implementations. -`VaultKeyValueOperations` follows the Vault CLI design. +javadoc:org.springframework.vault.core.VaultKeyValueOperations[] follows the Vault CLI design. That's the primary command line tool for Vault providing commands such as `vault kv get`, `vault kv put` and so on. You can use this API with both Key-Value engine versions by specifying the version and mount path. @@ -38,9 +38,9 @@ include::example$KeyValueV1.java[tags=keyValueApi] ---- ==== -`VaultKeyValueOperations` supports all Key-Value operations such as `put`, `get`, `delete`, `list`. +javadoc:org.springframework.vault.core.VaultKeyValueOperations[] supports all Key-Value operations such as `put`, `get`, `delete`, `list`. -Alternatively, the API can be used through `VaultTemplate` because of its direct mapping and simple use, as keys and responses map directly to input and output keys. +Alternatively, the API can be used through javadoc:org.springframework.vault.core.VaultTemplate[] because of its direct mapping and simple use, as keys and responses map directly to input and output keys. The following example illustrates writing and reading a secret at `mykey`. The `kv` secrets engine is mounted at `secret`: @@ -76,7 +76,7 @@ include::example$KeyValueV2.java[tags=keyValueApi] ---- ==== -`VaultKeyValueOperations` supports all Key-Value operations, such as `put`, `get`, `delete`, `list`. +javadoc:org.springframework.vault.core.VaultKeyValueOperations[] supports all Key-Value operations, such as `put`, `get`, `delete`, `list`. You can also interact with the specifics of the versioned key-value API. This is useful if you want to obtain a specific secret or you need access to the metadata. @@ -124,12 +124,12 @@ The following examples explain briefly the use of how to issue and revoke certif ---- include::example$PKI.java[tags=pkiApi] ---- -<1> Construct a certificate request by using the `VaultCertificateRequest` builder. +<1> Construct a certificate request by using the javadoc:org.springframework.vault.support.VaultCertificateRequest[] builder. <2> Request a certificate from Vault. Vault acts as certificate authority and responds with a signed X.509 certificate. -The actual response is a `CertificateBundle`. +The actual response is a javadoc:org.springframework.vault.support.CertificateBundle[]. <3> You can obtain generated certificates directly as Java KeyStore that contains public and private keys as well as the issuer certificate. KeyStore has a wide range of uses, which makes this format suitable to configure (for example a HTTP client, a database driver, or an SSL-secured HTTP server). -<4> `CertificateBundle` allows accessing the private key and the public and issuer certificates directly through the Java Cryptography Extension API. +<4> javadoc:org.springframework.vault.support.CertificateBundle[] allows accessing the private key and the public and issuer certificates directly through the Java Cryptography Extension API. <5> Once a certificate is no longer in use (or it was compromised), you can revoke it through its serial number. Vault includes the revoked certificate in its CRL. ==== @@ -212,19 +212,19 @@ The preceeding example uses simple strings for cryptographic operations. While it is a simple approach, it bears the risk of charset misconfiguration and is not binary-safe. Binary safety is required when the plain text uses a binary representation for data such as images, compressed data, or binary data structures. -To encrypt and decrypt binary data, use the `Plaintext` and `Ciphertext` value objects that can hold binary values: +To encrypt and decrypt binary data, use the javadoc:org.springframework.vault.support.Plaintext[] and javadoc:org.springframework.vault.support.Ciphertext[] value objects that can hold binary values: ==== [source,java,indent=0] ---- include::example$Transit.java[tags=encryptPlaintext] ---- -<1> Assuming a key `my-aes-key` is already in place, we're encrypting the `Plaintext` object. -In return, the `encrypt` method returns a `Ciphertext` object. -<2> The `Ciphertext` object can be used directly for decryption and returns a `Plaintext` object. +<1> Assuming a key `my-aes-key` is already in place, we're encrypting the javadoc:org.springframework.vault.support.Plaintext[] object. +In return, the `encrypt` method returns a javadoc:org.springframework.vault.support.Ciphertext[] object. +<2> The javadoc:org.springframework.vault.support.Ciphertext[] object can be used directly for decryption and returns a javadoc:org.springframework.vault.support.Plaintext[] object. ==== -`Plaintext` and `Ciphertext` come with a contextual object, `VaultTransitContext`. +javadoc:org.springframework.vault.support.Plaintext[] and javadoc:org.springframework.vault.support.Ciphertext[] come with a contextual object, javadoc:org.springframework.vault.support.VaultTransitContext[]. It is used to supply a nonce value for https://www.vaultproject.io/docs/secrets/transit#convergent-encryption[convergent encryption] and for a context value to make use of key derivation. Transit allows for signing plain text and verifying the signature for a given plain text. @@ -242,8 +242,8 @@ Internally, the hash gets computed and encrypted using the private key to create include::example$Transit.java[tags=signVerify] ---- <1> Signing requires an asymmetric key. You can use any Elliptic Curve Cryptography or RSA key type. Once the key is created, you have all the prerequisites in place to create a signature. -<2> The signature gets created for a plain text message. The returned `Signature` contains an ASCII-safe string that uses Base64 characters. -<3> To verify the signature, the verification requires a Signature object and the plain text message. As the return value, you get whether the signature was valid or not. +<2> The signature gets created for a plain text message. The returned javadoc:org.springframework.vault.support.Signature[] contains an ASCII-safe string that uses Base64 characters. +<3> To verify the signature, the verification requires a javadoc:org.springframework.vault.support.Signature[] object and the plain text message. As the return value, you get whether the signature was valid or not. ==== You can find more details about the https://www.vaultproject.io/api/secret/transit[Vault Transit Backend] in the Vault reference documentation. diff --git a/src/main/antora/resources/antora-resources/antora.yml b/src/main/antora/resources/antora-resources/antora.yml index abf4e804..5b71404a 100644 --- a/src/main/antora/resources/antora-resources/antora.yml +++ b/src/main/antora/resources/antora-resources/antora.yml @@ -8,7 +8,6 @@ asciidoc: springversion: ${spring.version} attribute-missing: 'warn' include-xml-namespaces: false - self-docs-root: https://docs.spring.io/spring-vault/reference/ spring-data-commons-docs-url: https://docs.spring.io/spring-data/commons/reference spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/current/api/ spring-framework-docs: https://docs.spring.io/spring-framework/reference/{springversionshort}