Add nullability annotations

Closes gh-972

Author: wilkinsona

docs/src/docs/asciidoc/documenting-your-api.adoc

@@ -5,6 +5,20 @@ This section provides more details about using Spring REST Docs to document your
 
 
 
+[[documenting-your-api-null-safety]]
+=== Null Safety
+Spring REST Docs is annotated with https://jspecify.dev/docs/start-here/[JSpecify ] annotations to declare the nullability of its API.
+To learn more about JSpecify, its https://jspecify.dev/docs/user-guide/[user guide] is recommended reading.
+
+The primary goal of declaring the nullability of the API is to prevent a `NullPointerException` from being thrown at runtime.
+This is achieved through build-time checks that are available with both Java and Kotlin.
+Performing the checks with Java requires some tooling such as https://github.com/uber/NullAway[NullAway] or an IDE that supports JSpecify annotations such as IntelliJ IDEA.
+The checks are available automatically with Kotlin which translates the JSpecify annotations into Kotlin's null safety.
+
+To learn more about null safety with Spring, refer to the {spring-framework-docs}/core/null-safety.html[Spring Framework reference documentation].
+
+
+
 [[documenting-your-api-hypermedia]]
 === Hypermedia
 

gradle/plugins/conventions/build.gradle

@@ -18,6 +18,7 @@ gradlePlugin {
 
 dependencies {
 	implementation(project(":toolchain"))
+	implementation("io.spring.gradle.nullability:nullability-plugin:0.0.2")
 	implementation("io.spring.javaformat:spring-javaformat-gradle-plugin:$javaFormatVersion")
 	implementation("io.spring.nohttp:nohttp-gradle:0.0.11")
 }

gradle/plugins/conventions/src/main/java/org/springframework/restdocs/build/conventions/JavaBasePluginConventions.java

@@ -19,6 +19,7 @@
 import java.util.List;
 import java.util.Map;
 
+import io.spring.gradle.nullability.NullabilityPlugin;
 import io.spring.javaformat.gradle.SpringJavaFormatPlugin;
 import org.gradle.api.JavaVersion;
 import org.gradle.api.Project;
@@ -49,6 +50,7 @@ class JavaBasePluginConventions extends Conventions<JavaBasePlugin> {
 
 	@Override
 	void apply(JavaBasePlugin plugin) {
+		configureNullability();
 		configureToolchains();
 		configureCheckstyle();
 		configureJavaFormat();
@@ -58,6 +60,10 @@ void apply(JavaBasePlugin plugin) {
 		configureDependencyManagement();
 	}
 
+	private void configureNullability() {
+		getProject().getPlugins().apply(NullabilityPlugin.class);
+	}
+
 	private void configureToolchains() {
 		getProject().getPlugins().apply(ToolchainPlugin.class);
 	}

spring-restdocs-asciidoctor/build.gradle

@@ -7,6 +7,8 @@ plugins {
 description = "Spring REST Docs Asciidoctor Extension"
 
 dependencies {
+	compileOnly("org.jspecify:jspecify")
+
 	implementation("org.asciidoctor:asciidoctorj")
 
 	testImplementation("org.apache.pdfbox:pdfbox")

spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/SnippetsDirectoryResolver.java

@@ -23,6 +23,8 @@
 import java.util.Map;
 import java.util.function.Supplier;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Resolves the directory from which snippets can be read for inclusion in an Asciidoctor
  * document. The resolved directory is absolute.
@@ -40,7 +42,12 @@ File getSnippetsDirectory(Map<String, Object> attributes) {
 
 	private File getMavenSnippetsDirectory(Map<String, Object> attributes) {
 		Path docdir = Paths.get(getRequiredAttribute(attributes, "docdir"));
-		return new File(findPom(docdir).getParent().toFile(), "target/generated-snippets").getAbsoluteFile();
+		Path pom = findPom(docdir);
+		Path parent = pom.getParent();
+		if (parent == null) {
+			throw new IllegalStateException("Pom '" + pom + "' has no parent directory");
+		}
+		return new File(parent.toFile(), "target/generated-snippets").getAbsoluteFile();
 	}
 
 	private Path findPom(Path docdir) {
@@ -65,7 +72,8 @@ private String getRequiredAttribute(Map<String, Object> attributes, String name)
 		return getRequiredAttribute(attributes, name, null);
 	}
 
-	private String getRequiredAttribute(Map<String, Object> attributes, String name, Supplier<String> fallback) {
+	private String getRequiredAttribute(Map<String, Object> attributes, String name,
+			@Nullable Supplier<String> fallback) {
 		String attribute = (String) attributes.get(name);
 		if (attribute == null || attribute.length() == 0) {
 			if (fallback != null) {

spring-restdocs-asciidoctor/src/main/java/org/springframework/restdocs/asciidoctor/package-info.java

@@ -17,4 +17,7 @@
 /**
  * Support for Asciidoctor.
  */
+@NullMarked
 package org.springframework.restdocs.asciidoctor;
+
+import org.jspecify.annotations.NullMarked;

spring-restdocs-core/src/main/java/org/springframework/restdocs/ManualRestDocumentation.java

@@ -18,8 +18,11 @@
 
 import java.io.File;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.extension.Extension;
 
+import org.springframework.util.Assert;
+
 /**
  * {@code ManualRestDocumentation} is used to manually manage the
  * {@link RestDocumentationContext}. Primarly intended for use with TestNG, but suitable
@@ -35,7 +38,7 @@ public final class ManualRestDocumentation implements RestDocumentationContextPr
 
 	private final File outputDirectory;
 
-	private StandardRestDocumentationContext context;
+	private @Nullable StandardRestDocumentationContext context;
 
 	/**
 	 * Creates a new {@code ManualRestDocumentation} instance that will generate snippets
@@ -68,9 +71,7 @@ private ManualRestDocumentation(File outputDirectory) {
 	 * @throws IllegalStateException if a context has already be created
 	 */
 	public void beforeTest(Class<?> testClass, String testMethodName) {
-		if (this.context != null) {
-			throw new IllegalStateException("Context already exists. Did you forget to call afterTest()?");
-		}
+		Assert.isNull(this.context, () -> "Context already exists. Did you forget to call afterTest()?");
 		this.context = new StandardRestDocumentationContext(testClass, testMethodName, this.outputDirectory);
 	}
 
@@ -84,6 +85,7 @@ public void afterTest() {
 
 	@Override
 	public RestDocumentationContext beforeOperation() {
+		Assert.notNull(this.context, () -> "Context is null. Did you forget to call beforeTest(Class, String)?");
 		this.context.getAndIncrementStepCount();
 		return this.context;
 	}

spring-restdocs-core/src/main/java/org/springframework/restdocs/RestDocumentationExtension.java

@@ -16,6 +16,7 @@
 
 package org.springframework.restdocs;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.extension.AfterEachCallback;
 import org.junit.jupiter.api.extension.BeforeEachCallback;
 import org.junit.jupiter.api.extension.Extension;
@@ -32,7 +33,7 @@
  */
 public class RestDocumentationExtension implements BeforeEachCallback, AfterEachCallback, ParameterResolver {
 
-	private final String outputDirectory;
+	private final @Nullable String outputDirectory;
 
 	/**
 	 * Creates a new {@code RestDocumentationExtension} that will use the default output
@@ -48,7 +49,7 @@ public RestDocumentationExtension() {
 	 * @param outputDirectory snippet output directory
 	 * @since 2.0.4
 	 */
-	public RestDocumentationExtension(String outputDirectory) {
+	public RestDocumentationExtension(@Nullable String outputDirectory) {
 		this.outputDirectory = outputDirectory;
 	}
 

spring-restdocs-core/src/main/java/org/springframework/restdocs/cli/CliDocumentation.java

@@ -18,6 +18,8 @@
 
 import java.util.Map;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.restdocs.snippet.Snippet;
 
 /**
@@ -80,7 +82,7 @@ public static Snippet curlRequest(CommandFormatter commandFormatter) {
 	 * @return the snippet that will document the curl request
 	 * @since 1.2.0
 	 */
-	public static Snippet curlRequest(Map<String, Object> attributes, CommandFormatter commandFormatter) {
+	public static Snippet curlRequest(@Nullable Map<String, Object> attributes, CommandFormatter commandFormatter) {
 		return new CurlRequestSnippet(attributes, commandFormatter);
 	}
 
@@ -126,7 +128,7 @@ public static Snippet httpieRequest(CommandFormatter commandFormatter) {
 	 * @return the snippet that will document the HTTPie request
 	 * @since 1.2.0
 	 */
-	public static Snippet httpieRequest(Map<String, Object> attributes, CommandFormatter commandFormatter) {
+	public static Snippet httpieRequest(@Nullable Map<String, Object> attributes, CommandFormatter commandFormatter) {
 		return new HttpieRequestSnippet(attributes, commandFormatter);
 	}
 

spring-restdocs-core/src/main/java/org/springframework/restdocs/cli/CliOperationRequest.java

@@ -26,8 +26,11 @@
 import java.util.Map.Entry;
 import java.util.Set;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpMethod;
+import org.springframework.lang.Contract;
 import org.springframework.restdocs.operation.OperationRequest;
 import org.springframework.restdocs.operation.OperationRequestPart;
 import org.springframework.restdocs.operation.RequestCookie;
@@ -55,7 +58,7 @@ boolean isPutOrPost() {
 		return HttpMethod.PUT.equals(this.delegate.getMethod()) || HttpMethod.POST.equals(this.delegate.getMethod());
 	}
 
-	String getBasicAuthCredentials() {
+	@Nullable String getBasicAuthCredentials() {
 		List<String> headerValue = this.delegate.getHeaders().get(HttpHeaders.AUTHORIZATION);
 		if (BasicAuthHeaderFilter.isBasicAuthHeader(headerValue)) {
 			return BasicAuthHeaderFilter.decodeBasicAuthHeader(headerValue);
@@ -132,7 +135,8 @@ public boolean allow(String name, List<String> value) {
 			return !(HttpHeaders.AUTHORIZATION.equals(name) && isBasicAuthHeader(value));
 		}
 
-		static boolean isBasicAuthHeader(List<String> value) {
+		@Contract("null -> false")
+		static boolean isBasicAuthHeader(@Nullable List<String> value) {
 			return value != null && (!value.isEmpty()) && value.get(0).startsWith("Basic ");
 		}