docs: document custom-interceptors config for the Java SDK generator

[devin-ai-integration]

Summary

custom-interceptors has shipped in the Java SDK generator since 3.41.0 (2026-03-03) but only ever appeared in the generator changelog, so a customer reading /learn/sdks/generators/java/configuration has no way to discover it. This adds the config option to the Java configuration reference and a usage section to the Java custom-code page.

Behavior documented here was verified empirically, not inferred from the changelog: two fern generate --local runs against fernapi/fern-java-sdk:4.16.0 on the same spec, differing only by config: custom-interceptors: true. With the flag, the generated builder gains

public YourApiClientBuilder addInterceptor(Interceptor interceptor)   // collects into List<Interceptor>
protected void setInterceptors(ClientOptions.Builder builder)          // applied to the OkHttpClient at build()

plus the matching ClientOptions.Builder.addInterceptor(...); the control run has none of them. setInterceptors is generated whenever the flag is on (it does not require enable-extensible-builders), which is why it's listed in the extensible-builder method reference table as conditional on custom-interceptors rather than on the builder flag.

Two review questions are answered from the generator source (ClientOptionsGenerator.java) and the java-sdk seed fixtures under seed/java-sdk/*/custom-interceptors/, each condensed to a clause on the page:

Ordering relative to RetryInterceptor. ClientOptions.Builder.build() registers interceptors in this order, and OkHttp invokes application interceptors in registration order:

httpClientBuilder
    .addInterceptor(new RetryInterceptor(...))            // only when no caller-supplied OkHttpClient
    .addInterceptor(new LoggingInterceptor(logger))
    .addInterceptor(new ResponseDecompressionInterceptor());
for (Interceptor interceptor : this.interceptors) {       // custom, last
    httpClientBuilder.addInterceptor(interceptor);
}

Custom interceptors sit innermost, so RetryInterceptor.retryChain()'s repeated chain.proceed(...) re-enters them on every attempt: a signing interceptor signs each attempt independently rather than replaying the first signature.

OAuth staged builders. 3.42.5 added interceptors/addInterceptor to the _Builder inner class and forwarding through token()/credentials(). The seed fixture confirms addInterceptor exists both on _Builder and on the auth-stage builders (_TokenAuth, _CredentialsAuth), so the existing builder().token(...).addInterceptor(...) example is already correct for OAuth APIs; the page notes registration works on either side of the auth call.

Link to Devin session: https://app.devin.ai/sessions/018daf6fd74d4413a3b89f4f5c706f96

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

🌿 Preview your docs: https://fern-preview-devin-1785769977-java-custom-interceptors-docs.docs.buildwithfern.com/learn

Here are the markdown pages you've updated:

• learn/sdks/generators/java/configuration
• learn/sdks/generators/java/custom-code

[github-actions]

📝 [vale] _{reported by reviewdog 🐶}
[Microsoft.Wordiness] Consider using 'all' instead of 'all of'.