From b4d191a26fd78d49c30bbb15d75bfa931b4d4cbe Mon Sep 17 00:00:00 2001
From: Connie Yau <conniey@microsoft.com>
Date: Mon, 4 Dec 2023 12:44:01 -0800
Subject: [PATCH] Schema Registry: Documentation fixes (#37913)

* Fix README.md. Fixes #37424

* Use public API for sample. Fixes #36970.

* Fixes #25860

* Update registerSchema docs. Fixes #25866
---
 .../README.md                                 |  4 +-
 .../azure-data-schemaregistry/README.md       |  4 +-
 .../SchemaRegistryAsyncClient.java            | 43 ++++++++++++-------
 .../schemaregistry/SchemaRegistryClient.java  | 42 +++++++++++-------
 ...hemaRegistryClientJavaDocCodeSnippets.java |  3 +-
 5 files changed, 58 insertions(+), 38 deletions(-)

diff --git a/sdk/schemaregistry/azure-data-schemaregistry-jsonschema/README.md b/sdk/schemaregistry/azure-data-schemaregistry-jsonschema/README.md
index e09d5dce1db57..dee6a9f04f609 100644
--- a/sdk/schemaregistry/azure-data-schemaregistry-jsonschema/README.md
+++ b/sdk/schemaregistry/azure-data-schemaregistry-jsonschema/README.md
@@ -5,7 +5,7 @@ Azure Schema Registry hosted in Azure Event Hubs, providing schema storage, vers
 provides a serializer capable of serializing and deserializing payloads containing Schema Registry schema
 identifiers and JSON encoded data.
 
-[Source code][source_code] | (Package yet to release) | [API reference documentation][api_reference_doc] | [Product Documentation][product_documentation] | [Samples][sample_readme]
+[Source code][source_code] | [Package (Maven)][package_maven] | [API reference documentation][api_reference_doc] | [Product Documentation][product_documentation] | [Samples][sample_readme]
 
 ## Getting started
 
@@ -141,7 +141,7 @@ When you submit a pull request, a CLA-bot will automatically determine whether y
 This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments.
 
 <!-- LINKS -->
-<!-- [package_maven]: https://central.sonatype.com/artifact/com.azure/azure-data-schemaregistry-jsonschema -->
+[package_maven]: https://central.sonatype.com/artifact/com.azure/azure-data-schemaregistry-jsonschema 
 [sample_readme]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/schemaregistry/azure-data-schemaregistry-jsonschema/src/samples
 [samples]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/schemaregistry/azure-data-schemaregistry-jsonschema/src/samples/java/com/azure/data/schemaregistry/jsonschema
 [address_type]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/schemaregistry/azure-data-schemaregistry-jsonschema/src/test/java/com/azure/data/schemaregistry/jsonschema/Address.java
diff --git a/sdk/schemaregistry/azure-data-schemaregistry/README.md b/sdk/schemaregistry/azure-data-schemaregistry/README.md
index 3e380d1ab608d..a40f41c0ba803 100644
--- a/sdk/schemaregistry/azure-data-schemaregistry/README.md
+++ b/sdk/schemaregistry/azure-data-schemaregistry/README.md
@@ -12,7 +12,7 @@ schema identifiers rather than full schemas.
 
 - A [Java Development Kit (JDK)][jdk_link], version 8 or later.
 - [Azure Subscription][azure_subscription]
-- An [Event Hubs namespace][event_hubs_namespace]
+- An [Event Hubs schema registry][event_hubs_namespace]
 
 ### Include the package
 
@@ -205,7 +205,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
 [azure_portal]: https://portal.azure.com
 [azure_identity]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/identity/azure-identity
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/identity/azure-identity/README.md#defaultazurecredential
-[event_hubs_namespace]: https://docs.microsoft.com/azure/event-hubs/event-hubs-about
+[event_hubs_namespace]: https://learn.microsoft.com/azure/event-hubs/create-schema-registry
 [jdk_link]: https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable
 [product_documentation]: https://aka.ms/schemaregistry
 [custom_subdomain]: https://docs.microsoft.com/azure/cognitive-services/authentication#create-a-resource-with-a-custom-subdomain
diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryAsyncClient.java b/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryAsyncClient.java
index a9dddb7cc9290..684d774f3bdac 100644
--- a/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryAsyncClient.java
+++ b/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryAsyncClient.java
@@ -139,8 +139,7 @@
  *
  * <!-- src_embed com.azure.data.schemaregistry.schemaregistryasyncclient.getschemawithresponse -->
  * <pre>
- * client.getSchemaWithResponse&#40;&quot;&#123;group-name&#125;&quot;,
- *         &quot;&#123;schema-name&#125;&quot;, 1, Context.NONE&#41;
+ * client.getSchemaWithResponse&#40;&quot;&#123;group-name&#125;&quot;, &quot;&#123;schema-name&#125;&quot;, 1&#41;
  *     .subscribe&#40;response -&gt; &#123;
  *         System.out.println&#40;&quot;Headers in HTTP response: &quot;&#41;;
  *
@@ -186,13 +185,19 @@ public String getFullyQualifiedNamespace() {
     }
 
     /**
-     * Registers a new schema in the specified schema group with the given schema name. If a schema
-     * <b>does not exist</b>does not exist with the same {@code groupName}, {@code name}, {@code format}, and
-     * {@code schemaDefinition}, it is added to the Schema Registry Instance and assigned a schema id. If a schema
-     * exists with a matching {@code groupName}, {@code name}, {@code format}, and {@code schemaDefinition}, the id of
-     * that schema is returned. If the Schema Registry instance contains an existing {@code groupName}, {@code name},
-     * and {@code format} but the {@code schemaDefinition} is different, it is considered a new version, and schema id
-     * is assigned to it.
+     * Registers a new schema in the specified schema group with the given schema name.  If a schema:
+     * 
+     * <ul>
+     * <li><b>does not exist</b> with the same {@code groupName}, {@code name}, {@code format}, and
+     * {@code schemaDefinition}, it is added to the Schema Registry Instance and assigned a new schema id.</li>
+     * 
+     * <li>exists with the same {@code groupName}, {@code name}, {@code format}, and {@code schemaDefinition},
+     * the id of that existing schema is returned.</li>
+     * 
+     * <li>exists with the same {@code groupName}, {@code name}, and {@code format} but the <u>{@code schemaDefinition}
+     * is different</u>, it is considered a new version. A new schema id is assigned to the schema and its schema id is
+     * returned.</li>
+     * </ul>
      *
      * @param groupName The schema group.
      * @param name The schema name.
@@ -213,13 +218,19 @@ public Mono<SchemaProperties> registerSchema(String groupName, String name, Stri
     }
 
     /**
-     * Registers a new schema in the specified schema group with the given schema name. If a schema
-     * <b>does not exist</b> with the same {@code groupName}, {@code name}, {@code format}, and
-{@code schemaDefinition}, it is added to the Schema Registry Instance and assigned a schema id. If a schema
-     * exists with a matching {@code groupName}, {@code name}, {@code format}, and {@code schemaDefinition}, the id of
-     * that schema is returned. If the Schema Registry instance contains an existing {@code groupName}, {@code name},
-     * and {@code format} but the {@code schemaDefinition} is different, it is considered a new version, and schema id
-     * is assigned to it.
+     * Registers a new schema in the specified schema group with the given schema name.  If a schema:
+     * 
+     * <ul>
+     * <li><b>does not exist</b> with the same {@code groupName}, {@code name}, {@code format}, and
+     * {@code schemaDefinition}, it is added to the Schema Registry Instance and assigned a new schema id.</li>
+     * 
+     * <li>exists with the same {@code groupName}, {@code name}, {@code format}, and {@code schemaDefinition},
+     * the id of that existing schema is returned.</li>
+     * 
+     * <li>exists with the same {@code groupName}, {@code name}, and {@code format} but the <u>{@code schemaDefinition}
+     * is different</u>, it is considered a new version. A new schema id is assigned to the schema and its schema id is
+     * returned.</li>
+     * </ul>
      *
      * @param groupName The schema group.
      * @param name The schema name.
diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClient.java b/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClient.java
index 8286a22293b4c..18ff41bb49063 100644
--- a/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClient.java
+++ b/sdk/schemaregistry/azure-data-schemaregistry/src/main/java/com/azure/data/schemaregistry/SchemaRegistryClient.java
@@ -171,14 +171,19 @@ public String getFullyQualifiedNamespace() {
     }
 
     /**
-     * <p>Registers a new schema in the specified schema group with the given schema name.</p>
-     *
-     * <p>If a schema <b>does not exist</b> with the same {@code groupName}, {@code name}, {@code format}, and
-     * {@code schemaDefinition}, it is added to Schema Registry. If a schema exists with a matching {@code groupName},
-     * {@code name}, {@code format}, and {@code schemaDefinition}, the id of that schema is returned. If the Schema
-     * Registry instance contains an existing {@code groupName}, {@code name}, and {@code format} but the
-     * {@code schemaDefinition} is different, it is considered a new version; it will receive a new schema id and that
-     * will be returned.</p>
+     * Registers a new schema in the specified schema group with the given schema name.  If a schema:
+     * 
+     * <ul>
+     * <li><b>does not exist</b> with the same {@code groupName}, {@code name}, {@code format}, and
+     * {@code schemaDefinition}, it is added to the Schema Registry Instance and assigned a new schema id.</li>
+     * 
+     * <li>exists with the same {@code groupName}, {@code name}, {@code format}, and {@code schemaDefinition},
+     * the id of that existing schema is returned.</li>
+     * 
+     * <li>exists with the same {@code groupName}, {@code name}, and {@code format} but the <u>{@code schemaDefinition}
+     * is different</u>, it is considered a new version. A new schema id is assigned to the schema and its schema id is
+     * returned.</li>
+     * </ul>
      *
      * @param groupName The schema group.
      * @param name The schema name.
@@ -198,14 +203,19 @@ public SchemaProperties registerSchema(String groupName, String name, String sch
     }
 
     /**
-     * <p>Registers a new schema in the specified schema group with the given schema name.</p>
-     *
-     * <p>If a schema <b>does not exist</b> with the same {@code groupName}, {@code name}, {@code format}, and
-     * {@code schemaDefinition}, it is added to Schema Registry. If a schema exists with a matching {@code groupName},
-     * {@code name}, {@code format}, and {@code schemaDefinition}, the id of that schema is returned. If the Schema
-     * Registry instance contains an existing {@code groupName}, {@code name}, and {@code format} but the
-     * {@code schemaDefinition} is different, it is considered a new version; it will receive a new schema id and that
-     * will be returned.</p>
+     * Registers a new schema in the specified schema group with the given schema name.  If a schema:
+     * 
+     * <ul>
+     * <li><b>does not exist</b> with the same {@code groupName}, {@code name}, {@code format}, and
+     * {@code schemaDefinition}, it is added to the Schema Registry Instance and assigned a new schema id.</li>
+     * 
+     * <li>exists with the same {@code groupName}, {@code name}, {@code format}, and {@code schemaDefinition},
+     * the id of that existing schema is returned.</li>
+     * 
+     * <li>exists with the same {@code groupName}, {@code name}, and {@code format} but the <u>{@code schemaDefinition}
+     * is different</u>, it is considered a new version. A new schema id is assigned to the schema and its schema id is
+     * returned.</li>
+     * </ul>
      *
      * @param groupName The schema group.
      * @param name The schema name.
diff --git a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/SchemaRegistryClientJavaDocCodeSnippets.java b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/SchemaRegistryClientJavaDocCodeSnippets.java
index 4a5ff11866b0a..694a94cd5a33d 100644
--- a/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/SchemaRegistryClientJavaDocCodeSnippets.java
+++ b/sdk/schemaregistry/azure-data-schemaregistry/src/samples/java/com/azure/data/schemaregistry/SchemaRegistryClientJavaDocCodeSnippets.java
@@ -170,8 +170,7 @@ public void getSchemaWithResponseAsync() {
         SchemaRegistryAsyncClient client = buildAsyncClient();
 
         // BEGIN: com.azure.data.schemaregistry.schemaregistryasyncclient.getschemawithresponse
-        client.getSchemaWithResponse("{group-name}",
-                "{schema-name}", 1, Context.NONE)
+        client.getSchemaWithResponse("{group-name}", "{schema-name}", 1)
             .subscribe(response -> {
                 System.out.println("Headers in HTTP response: ");