Add Azure Core OkHttp Javadocs (#38014)

sdk/core/azure-core-http-okhttp/src/main/java/com/azure/core/http/okhttp/OkHttpAsyncClientProvider.java

@@ -12,7 +12,13 @@
 import java.util.concurrent.TimeUnit;
 
 /**
- * An {@link HttpClientProvider} that provides an implementation of HttpClient based on OkHttp.
+ * <p>This class provides an OkHttp-based implementation for the {@link HttpClientProvider} interface.
+ * It is designed to create instances of {@link HttpClient} using OkHttp as the underlying client.</p>
+ *
+ * @see com.azure.core.http.okhttp
+ * @see HttpClientProvider
+ * @see HttpClient
+ * @see OkHttpAsyncHttpClientBuilder
  */
 public final class OkHttpAsyncClientProvider implements HttpClientProvider {
     private static final boolean AZURE_ENABLE_HTTP_CLIENT_SHARING =

sdk/core/azure-core-http-okhttp/src/main/java/com/azure/core/http/okhttp/OkHttpAsyncHttpClient.java

@@ -37,7 +37,26 @@
 import java.io.UncheckedIOException;
 
 /**
- * HttpClient implementation for OkHttp.
+ * This class provides a OkHttp-based implementation for the {@link HttpClient} interface. Creating an instance of this
+ * class can be achieved by using the {@link OkHttpAsyncHttpClientBuilder} class, which offers OkHttp-specific API for
+ * features such as {@link OkHttpAsyncHttpClientBuilder#proxy(ProxyOptions) setProxy configuration}, and much more.
+ *
+ * <p><strong>Sample: Construct OkHttpAsyncHttpClient with Default Configuration</strong></p>
+ *
+ * <p>The following code sample demonstrates the creation of a OkHttp HttpClient that uses port 80 and has no proxy.</p>
+ *
+ * <!-- src_embed com.azure.core.http.okhttp.instantiation-simple -->
+ * <pre>
+ * HttpClient client = new OkHttpAsyncHttpClientBuilder&#40;&#41;
+ *         .build&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.core.http.okhttp.instantiation-simple -->
+ *
+ * <p>For more ways to instantiate OkHttpAsyncHttpClient, refer to {@link OkHttpAsyncHttpClientBuilder}.</p>
+ *
+ * @see com.azure.core.http.okhttp
+ * @see OkHttpAsyncHttpClientBuilder
+ * @see HttpClient
  */
 class OkHttpAsyncHttpClient implements HttpClient {
 

sdk/core/azure-core-http-okhttp/src/main/java/com/azure/core/http/okhttp/OkHttpAsyncHttpClientBuilder.java

@@ -26,6 +26,73 @@
 
 /**
  * Builder class responsible for creating instances of {@link com.azure.core.http.HttpClient} backed by OkHttp.
+ * The client built from this builder can support sending requests synchronously and asynchronously.
+ * Use {@link com.azure.core.http.HttpClient#sendSync(HttpRequest, Context)} to send the provided request
+ * synchronously with contextual information.
+ *
+ * <p><strong>Building a new HttpClient instance</strong></p>
+ *
+ * <!-- src_embed com.azure.core.http.okhttp.instantiation-simple -->
+ * <pre>
+ * HttpClient client = new OkHttpAsyncHttpClientBuilder&#40;&#41;
+ *         .build&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.core.http.okhttp.instantiation-simple -->
+ *
+ * <p><strong>Building a new HttpClient instance using http proxy.</strong></p>
+ *
+ * <p>Configuring the OkHttp client with a proxy is relevant when your application needs to communicate with Azure
+ * services through a proxy server.</p>
+ *
+ * <!-- src_embed com.azure.core.http.okhttp.OkHttpAsyncHttpClientBuilder.proxy#ProxyOptions -->
+ * <pre>
+ * final String proxyHost = &quot;&lt;proxy-host&gt;&quot;; &#47;&#47; e.g. localhost
+ * final int proxyPort = 9999; &#47;&#47; Proxy port
+ * ProxyOptions proxyOptions = new ProxyOptions&#40;ProxyOptions.Type.HTTP,
+ *         new InetSocketAddress&#40;proxyHost, proxyPort&#41;&#41;;
+ * HttpClient client = new OkHttpAsyncHttpClientBuilder&#40;&#41;
+ *         .proxy&#40;proxyOptions&#41;
+ *         .build&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.core.http.okhttp.OkHttpAsyncHttpClientBuilder.proxy#ProxyOptions -->
+ *
+ * <p><strong>Building a new HttpClient instance with connection timeout.</strong></p>
+ *
+ * <p>Setting a reasonable connection timeout is particularly important in scenarios where network conditions might
+ * be unpredictable or where the server may not be responsive.</p>
+ *
+ * <!-- src_embed com.azure.core.http.okhttp.OkHttpAsyncHttpClientBuilder#connectionTimeout -->
+ * <pre>
+ * final Duration connectionTimeout = Duration.ofSeconds&#40;250&#41;; &#47;&#47; connection timeout of 250 seconds
+ * HttpClient client = new OkHttpAsyncHttpClientBuilder&#40;&#41;
+ *         .connectionTimeout&#40;connectionTimeout&#41;
+ *         .build&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.core.http.okhttp.OkHttpAsyncHttpClientBuilder#connectionTimeout -->
+ *
+ * <p><strong>Building a new HttpClient instance with HTTP/2 Support.</strong></p>
+ *
+ * <!-- src_embed com.azure.core.http.okhttp.instantiation-simple -->
+ * <pre>
+ * HttpClient client = new OkHttpAsyncHttpClientBuilder&#40;&#41;
+ *         .build&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.core.http.okhttp.instantiation-simple -->
+ *
+ * <p>It is also possible to create a OkHttp HttpClient that only supports HTTP/2.</p>
+ *
+ * <!-- src_embed readme-sample-useHttp2OnlyWithConfiguredOkHttpClient -->
+ * <pre>
+ * &#47;&#47; Constructs an HttpClient that only supports HTTP&#47;2.
+ * HttpClient client = new OkHttpAsyncHttpClientBuilder&#40;new OkHttpClient.Builder&#40;&#41;
+ *     .protocols&#40;Collections.singletonList&#40;Protocol.H2_PRIOR_KNOWLEDGE&#41;&#41;
+ *     .build&#40;&#41;&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end readme-sample-useHttp2OnlyWithConfiguredOkHttpClient  -->
+ *
+ * @see HttpClient
+ * @see OkHttpAsyncHttpClient
  */
 public class OkHttpAsyncHttpClientBuilder {
 

sdk/core/azure-core-http-okhttp/src/main/java/com/azure/core/http/okhttp/package-info.java

@@ -2,6 +2,77 @@
 // Licensed under the MIT License.
 
 /**
- * Package containing OkHttp HTTP client plugin for azure-core.
+ * <p><a href="https://learn.microsoft.com/en-us/java/api/overview/azure/core-http-okhttp-readme?view=azure-java-stable">
+ * Azure Core Http OkHttp</a> client library is a plugin for the azure-core HTTP client API. It allows you to use OkHttp
+ * as the underlying HTTP client for communicating with Azure services. OkHttp is a popular and efficient HTTP client
+ * that supports features such as HTTP/2, connection pooling, compression, and caching. To use the OkHttp client library,
+ * you need to include the dependency in your project and configure it when creating a service client.
+ * For more details refer to our <a href="https://learn.microsoft.com/azure/developer/java/sdk/http-client-pipeline#http-clients">conceptual documentation</a>.</p>
+ *
+ * <p><strong>Sample: Construct OkHttpAsyncHttpClient with Default Configuration</strong></p>
+ *
+ * <p>The following code sample demonstrates the creation of a OkHttp HttpClient that uses port 80 and has no proxy.</p>
+ *
+ * <!-- src_embed readme-sample-createBasicClient -->
+ * <pre>
+ * HttpClient client = new OkHttpAsyncHttpClientBuilder&#40;&#41;.build&#40;&#41;;
+ * </pre>
+ * <!-- end readme-sample-createBasicClient  -->
+ *
+ * <hr>
+ *
+ * <h2><strong>Using OkHttpAsyncHttpClient with Http Proxy</strong></h2>
+ *
+ * <p>Configuring the OkHttp client with a proxy in the context of Azure Java SDK is relevant when your application needs
+ * to communicate with Azure services through a proxy server. For more details refer to our
+ * <a href="https://learn.microsoft.com/azure/developer/java/sdk/proxying#http-proxy-configuration">conceptual documentation</a>.</p>
+ *
+ * <p>The following code sample demonstrates the creation of a OkHttp HttpClient that is using a proxy.</p>
+ *
+ * <!-- src_embed com.azure.core.http.okhttp.OkHttpAsyncHttpClientBuilder.proxy#ProxyOptions -->
+ * <pre>
+ * final String proxyHost = &quot;&lt;proxy-host&gt;&quot;; &#47;&#47; e.g. localhost
+ * final int proxyPort = 9999; &#47;&#47; Proxy port
+ * ProxyOptions proxyOptions = new ProxyOptions&#40;ProxyOptions.Type.HTTP,
+ *         new InetSocketAddress&#40;proxyHost, proxyPort&#41;&#41;;
+ * HttpClient client = new OkHttpAsyncHttpClientBuilder&#40;&#41;
+ *         .proxy&#40;proxyOptions&#41;
+ *         .build&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.core.http.okhttp.OkHttpAsyncHttpClientBuilder.proxy#ProxyOptions  -->
+ *
+ * <hr>
+ *
+ * <h2><strong>Using OkHttpAsyncHttpClient with HTTP/2 Support</strong></h2>
+ *
+ * <p>The following code sample demonstrates the creation of a OkHttp HttpClient that supports both the HTTP/1.1 and
+ * HTTP/2 protocols, with HTTP/2 being the preferred protocol.</p>
+ *
+ * <!-- src_embed readme-sample-useHttp2WithConfiguredOkHttpClient -->
+ * <pre>
+ * &#47;&#47; Constructs an HttpClient that supports both HTTP&#47;1.1 and HTTP&#47;2 with HTTP&#47;2 being the preferred protocol.
+ * &#47;&#47; This is the default handling for OkHttp.
+ * HttpClient client = new OkHttpAsyncHttpClientBuilder&#40;new OkHttpClient.Builder&#40;&#41;
+ *     .protocols&#40;Arrays.asList&#40;Protocol.HTTP_2, Protocol.HTTP_1_1&#41;&#41;
+ *     .build&#40;&#41;&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end readme-sample-useHttp2WithConfiguredOkHttpClient  -->
+ *
+ * <p>It is also possible to create a OkHttp HttpClient that only supports HTTP/2.</p>
+ *
+ * <!-- src_embed readme-sample-useHttp2OnlyWithConfiguredOkHttpClient -->
+ * <pre>
+ * &#47;&#47; Constructs an HttpClient that only supports HTTP&#47;2.
+ * HttpClient client = new OkHttpAsyncHttpClientBuilder&#40;new OkHttpClient.Builder&#40;&#41;
+ *     .protocols&#40;Collections.singletonList&#40;Protocol.H2_PRIOR_KNOWLEDGE&#41;&#41;
+ *     .build&#40;&#41;&#41;
+ *     .build&#40;&#41;;
+ * </pre>
+ * <!-- end readme-sample-useHttp2OnlyWithConfiguredOkHttpClient  -->
+ *
+ * @see com.azure.core.http.okhttp.OkHttpAsyncHttpClient
+ * @see com.azure.core.http.okhttp.OkHttpAsyncHttpClientBuilder
+ * @see okhttp3.OkHttpClient
  */
 package com.azure.core.http.okhttp;