Merge pull request #888 from saragluna/xiada/improve-refdoc

Improve the refdocs

docs/src/main/asciidoc/_configprops.adoc

@@ -119,7 +119,7 @@
 |spring.cloud.azure.client.http.response-timeout |  | Amount of time used when waiting for a server to reply.
 |spring.cloud.azure.client.http.write-timeout |  | Amount of time each request being sent over the wire.
 |spring.cloud.azure.compatibility-verifier.compatible-boot-versions |  | Comma-delimited list of Spring Boot versions that are compatible with current Spring Cloud Azure's version.
-|spring.cloud.azure.compatibility-verifier.enabled | `false` | Whether to enable the Spring Cloud Azure compatibility verifier.
+|spring.cloud.azure.compatibility-verifier.enabled | `true` | Whether to enable the Spring Cloud Azure compatibility verifier.
 |spring.cloud.azure.cosmos.client-telemetry-enabled |  | Whether to enable client telemetry which will periodically collect database operations aggregation statistics, system information like cpu/memory and send it to cosmos monitoring service, which will be helpful during debugging.
 |spring.cloud.azure.cosmos.client.application-id |  | Represents current application and is used for telemetry/monitoring purposes.
 |spring.cloud.azure.cosmos.connection-mode |  | Connection mode to be used by the client in the Azure Cosmos DB database service.

docs/src/main/asciidoc/_known-issues.adoc

@@ -1,8 +1,5 @@
 == Known Issues
 
-=== Error Logs When Using Defaultazurecredential
-
-There could be some `ERROR` logs be printed out while the `DefaultAzureCredential` running the chain and trying to find the first available credential. It doesn't mean the `DefaultAzureCredential` is broken or unavailable. Meanwhile, we'll keep improving this logging experience.
 
 
 

docs/src/main/asciidoc/_migration-guide-for-4.0.adoc

@@ -217,7 +217,7 @@ configurations can be divided into five categories:
 |*spring.cloud.azure*.retry |To configure the retry options apply to all Azure SDK clients. The retry options have supported part of the SDKs, there's no `spring.cloud.azure.cosmos.retry`.
 |===
 
-Check link:appendix.html[here] for a full list of configurations.
+Check link:appendix.html#_global_properties[Global Properties] for a full list of global configurations.
 
 ==== Each SDK Configurations
 
@@ -1420,9 +1420,9 @@ Legacy configuration:
 spring:
   cloud:
     azure:
-      client-id: ${CLIENT_ID}
-      client-secret: ${CLIENT_SECRET}
-      tenant-id: ${TENANT_ID}
+      client-id: ${AZURE_CLIENT_ID}
+      client-secret: ${AZURE_CLIENT_SECRET}
+      tenant-id: ${AZURE_TENANT_ID}
       resource-group: ${EVENTHUB_RESOURCE_GROUP}
       eventhub:
         namespace: ${EVENTHUB_NAMESPACE}
@@ -1436,11 +1436,11 @@ spring:
   cloud:
     azure:
       credential:
-        client-id: ${CLIENT_ID}
-        client-secret: ${CLIENT_SECRET}
+        client-id: ${AZURE_CLIENT_ID}
+        client-secret: ${AZURE_CLIENT_SECRET}
       profile:
-        tenant-id: ${TENANT_ID}
-        subscription-id: ${SUBSCRIPTION_ID}
+        tenant-id: ${AZURE_TENANT_ID}
+        subscription-id: ${AZURE_SUBSCRIPTION_ID}
       eventhubs:
         namespace: ${EVENTHUB_NAMESPACE}
         resource:
@@ -1457,10 +1457,10 @@ spring:
   cloud:
     azure:
       credential:
-        client-id: ${CLIENT_ID}
-        client-secret: ${CLIENT_SECRET}
+        client-id: ${AZURE_CLIENT_ID}
+        client-secret: ${AZURE_CLIENT_SECRET}
       profile:
-        tenant-id: ${TENANT_ID}
+        tenant-id: ${AZURE_TENANT_ID}
       eventhubs:
         namespace: ${EVENTHUB_NAMESPACE}
 ----
@@ -1612,9 +1612,9 @@ Legacy configuration:
 spring:
   cloud:
     azure:
-      client-id: ${CLIENT_ID}
-      client-secret: ${CLIENT_SECRET}
-      tenant-id: ${TENANT_ID}
+      client-id: ${AZURE_CLIENT_ID}
+      client-secret: ${AZURE_CLIENT_SECRET}
+      tenant-id: ${AZURE_TENANT_ID}
       resource-group: ${SERVICEBUS_RESOURCE_GROUP}
       servicebus:
         namespace: ${SERVICEBUS_NAMESPACE}
@@ -1628,11 +1628,11 @@ spring:
   cloud:
     azure:
       credential:
-        client-id: ${CLIENT_ID}
-        client-secret: ${CLIENT_SECRET}
+        client-id: ${AZURE_CLIENT_ID}
+        client-secret: ${AZURE_CLIENT_SECRET}
       profile:
-        tenant-id: ${TENANT_ID}
-        subscription-id: ${SUBSCRIPTION_ID}
+        tenant-id: ${AZURE_TENANT_ID}
+        subscription-id: ${AZURE_SUBSCRIPTION_ID}
       servicebus:
         namespace: ${SERVICEBUS_NAMESPACE}
         resource:
@@ -1649,10 +1649,10 @@ spring:
   cloud:
     azure:
       credential:
-        client-id: ${CLIENT_ID}
-        client-secret: ${CLIENT_SECRET}
+        client-id: ${AZURE_CLIENT_ID}
+        client-secret: ${AZURE_CLIENT_SECRET}
       profile:
-        tenant-id: ${TENANT_ID}
+        tenant-id: ${AZURE_TENANT_ID}
       servicebus:
         namespace: ${SERVICEBUS_NAMESPACE}
 ----

docs/src/main/asciidoc/configuration.adoc

@@ -51,37 +51,46 @@ There are some properties that could be shared among different Azure services, f
 
 NOTE: Properties configured under each Azure service will override the global configurations.
 
-Spring Cloud Azure unifies configuration properties' prefixes to `spring.cloud.azure` since 4.0, which will make configuration properties more consistent and more intuitive. Here's a quick review of the prefixes of supported Azure services.
+Spring Cloud Azure unifies configuration properties' prefixes to `spring.cloud.azure` since 4.0, which will make configuration properties more consistent and more intuitive. Here's a quick review of the serivce specific properties.
 
 .Service specific properties
-[cols="<50,<50", options="header"]
+[cols="<3,<3,<3", options="header"]
 |===
-|Azure Service |Configuration Property Prefix 
+|Azure Service |Configuration Property Prefix | Configuration Properties Link
 
 |Azure App Configuration 
 |spring.cloud.azure.*appconfiguration*
+|link:appendix.html#_azure_app_configuration_proeprties[App Configuration Properties]
 
 |Azure Cosmos DB 
 |spring.cloud.azure.*cosmos*
+|link:appendix.html#_azure_cosmos_proeprties[Cosmos Properties]
 
 |Azure Event Hubs 
 |spring.cloud.azure.*eventhubs*
+|link:appendix.html#_azure_event_hubs_proeprties[Event Hubs Properties]
 
-|Azure Key Vault Certificate 
+|Azure Key Vault Certificates
 |spring.cloud.azure.*keyvault.certificate*
+|link:appendix.html#_azure_key_vault_certificates_proeprties[Key Vault Certificates Properties]
 
-|Azure Key Vault Secret 
+|Azure Key Vault Secrets 
 |spring.cloud.azure.*keyvault.secret*
+|link:appendix.html#_azure_key_vault_secrets_proeprties[Key Vault Secrets Properties]
 
 |Azure Service Bus 
 |spring.cloud.azure.*servicebus*
+|link:appendix.html#_azure_service_bus_proeprties[Service Bus Properties]
 
 |Azure Storage Blob
 |spring.cloud.azure.*storage.blob*
+|link:appendix.html#_azure_storage_blob_proeprties[Storage Blob Properties]
 
 |Azure Storage File Share 
 |spring.cloud.azure.*storage.fileshare*
+|link:appendix.html#_azure_storage_file_share_proeprties[Storage File Share Properties]
 
 |Azure Storage Queue
 |spring.cloud.azure.*storage.queue*
+|link:appendix.html#_azure_storage_queue_proeprties[Storage Queue Properties]
 |===

docs/src/main/asciidoc/resource-manager.adoc

@@ -51,11 +51,11 @@ spring:
   cloud:
     azure:
       credential:
-        client-id: ${CLIENT_ID}
-        client-secret: ${CLIENT_SECRET}
+        client-id: ${AZURE_CLIENT_ID}
+        client-secret: ${AZURE_CLIENT_SECRET}
       profile:
-        tenant-id: ${TENANT_ID}
-        subscription-id: ${SUBSCRIPTION_ID}
+        tenant-id: ${AZURE_TENANT_ID}
+        subscription-id: ${AZURE_SUBSCRIPTION_ID}
       <azure-service>:
         namespace: ${SERVICEBUS_NAMESPACE}
         resource:

docs/src/main/asciidoc/secret-management.adoc

@@ -65,9 +65,9 @@ public class SampleApplication implements CommandLineRunner {
 
 Key Vault secret name only support characters in `[0-9a-zA-Z-]`. Refs: link:https://docs.microsoft.com/azure/key-vault/general/about-keys-secrets-certificates#vault-name-and-object-name[Vault-name and Object-name]. If your property name contains other characters, you can use these workarounds:
 
--  Use `-` instead of `.` in secret name. `.` is not supported in secret name. If your application have property name which contains `.`, like `spring.datasource.url`, just replace `.` to `-` when save secret in Azure Key Vault. For example: Save `spring-datasource-url` in Azure Key Vault. In your application, you can still use `spring.datasource.url` to retrieve property value.
+-  Use `-` instead of `.` in secret name. `.` isn't supported in secret name. If your application have property name which contains `.`, like `spring.datasource.url`, just replace `.` to `-` when save secret in Azure Key Vault. For example: Save `spring-datasource-url` in Azure Key Vault. In your application, you can still use `spring.datasource.url` to retrieve property value.
 
-**NOTE**: This method can not satisfy requirement like `spring.datasource-url`. When you save `spring-datasource-url` in Key Vault, only `spring.datasource.url` and `spring-datasource-url` is supported to retrieve property value, `spring.datasource-url` is not supported. To handle this case, please refer to the following option: Use property placeholders.
+NOTE: This method can not satisfy requirement like `spring.datasource-url`. When you save `spring-datasource-url` in Key Vault, only `spring.datasource.url` and `spring-datasource-url` is supported to retrieve property value, `spring.datasource-url` isn't supported. To handle this case, please refer to the following option: Use property placeholders.
 
 -  Use property placeholders. For example: setting this property in your application.properties: `property.with.special.character_=${propertyWithoutSpecialCharacter}`. The application will get  `propertyWithoutSpecialCharacter` key name and assign its value to `property.with.special.character_`.
 
@@ -81,7 +81,7 @@ If you stored 1000 secrets in the Key Vault, and you just want to use 3 of them.
 
 ==== Setting Refresh Interval
 
-By default, the secrets in `KeyVaultPropertySource` will refresh every 30 minutes. You can configure the time by `spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval`. For example: `spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval=60m` means refresh every 60 minutes. Set to `0` to disable auto-refresh.
+By default, the secrets in `KeyVaultPropertySource` will refresh every 30 minutes. You can configure the time by `spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval`. For example: `spring.cloud.azure.keyvault.secret.property-sources[].refresh-interval=60m` means refresh every 60 minutes. Set to `0` to disable auto refresh.
 
 ==== PropertySource Priority
 
@@ -89,7 +89,7 @@ If key exists in multiple PropertySources, which will take effect is decided by
 
 - If there is no `SystemEnvironmentPropertySource` in PropertySource list, then `KeyVaultPropertySource` will take the highest priority.
 - If there is `SystemEnvironmentPropertySource` in PropertySource list, then `SystemEnvironmentPropertySource` have higher priority than KeyVaultPropertySource. Which means you can use environment variable to override the Key Vault secret value in your application.
-- If there is multiple KeyVaultPropertySource in PropertySource list, then the definition order is the priority order. Take above sample as example, `key-vault-property-souece-1` has higher priority than `key-vault-property-souece-2`.
+- If there are multiple KeyVaultPropertySource in PropertySource list, then the definition order is the priority order. Take above sample as example, `key-vault-property-souece-1` has higher priority than `key-vault-property-souece-2`.
 
 ==== All Configurable Properties
 
@@ -101,7 +101,7 @@ If key exists in multiple PropertySources, which will take effect is decided by
 | *spring.cloud.azure.keyvault.secret*.property-sources[].name            |                                  | Name of this property source.
 | *spring.cloud.azure.keyvault.secret*.property-sources[].endpoint        |                                  | Azure Key Vault endpoint.
 | *spring.cloud.azure.keyvault.secret*.property-sources[].case-sensitive  | false                            | Whether the secret keys are case-sensitive.
-| *spring.cloud.azure.keyvault.secret*.property-sources[].secret-keys     |                                  | The secret keys supported for this property source. All keys be retrieved if this property is not configured.
+| *spring.cloud.azure.keyvault.secret*.property-sources[].secret-keys     |                                  | The secret keys supported for this property source. All keys be retrieved if this property is missing.
 | *spring.cloud.azure.keyvault.secret*.property-sources[].refresh-interval| 30m                              | Time interval to refresh all Key Vault secrets.
 | *spring.cloud.azure.keyvault.secret*.property-sources[].service-version |                                  | Secret service version used when making API requests.
 | *spring.cloud.azure.keyvault.secret*.property-sources[].client          |                                  | Client related properties.
@@ -112,9 +112,10 @@ If key exists in multiple PropertySources, which will take effect is decided by
 |===
 
 - Please refer to link:index.html#authorize-access-with-azure-active-directory[Authorize access with Azure AD] to make sure the link:https://docs.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals#service-principal-object[security principal] has been granted the sufficient permission to access the Azure Key Vault Secrets.
-- If common properties like `client`, `credential`, `profile`, `proxy`, `retry` are not configured in `spring.cloud.azure.keyvault.secret.property-sources[].xxx`, `spring.cloud.azure.xxx` will be used. Please refer to link:index.html#configuration[Configuration] to get more information about these common properties.
+- If common properties like `client`, `credential`, `profile`, `proxy`, `retry` aren't configured in `spring.cloud.azure.keyvault.secret.property-sources[].xxx`, `spring.cloud.azure.xxx` will be used. Please refer to link:index.html#configuration[Configuration] to get more information about these common properties.
 - Please refer to link:appendix.html#_configuration_properties[Configuration Properties] to get more information about nested properties.
 
 === Samples
 
 Sample project: link:https://github.com/Azure-Samples/azure-spring-boot-samples/tree/spring-cloud-azure_{project-version}/keyvault/spring-cloud-azure-starter-keyvault-secrets/property-source[property-source].
+

docs/src/main/asciidoc/spring-cloud-stream-support.adoc

@@ -282,10 +282,10 @@ spring:
   cloud:
     azure:
       credential:
-        client-id: ${SERVICE_PRINCIPAL_ID}
-        client-secret: ${SERVICE_PRINCIPAL_SECRET}
+        client-id: ${AZURE_CLIENT_ID}
+        client-secret: ${AZURE_CLIENT_SECRET}
       profile:
-        tenant-id: ${TENANT_ID}
+        tenant-id: ${AZURE_TENANT_ID}
       eventhubs:
         namespace: ${EVENTHUB_NAMESPACE}
         processor:
@@ -844,10 +844,10 @@ spring:
   cloud:
     azure:
       credential:
-        client-id: ${CLIENT_ID}
-        client-secret: ${CLIENT_SECRET}
+        client-id: ${AZURE_CLIENT_ID}
+        client-secret: ${AZURE_CLIENT_SECRET}
       profile:
-        tenant-id: ${TENANT_ID}
+        tenant-id: ${AZURE_TENANT_ID}
       servicebus:
         namespace: ${SERVICEBUS_NAMESPACE}
     stream:

docs/src/main/asciidoc/spring-data-support.adoc

@@ -4,7 +4,6 @@
 
 link:https://azure.microsoft.com/services/cosmos-db/[Azure Cosmos DB] is a globally-distributed database service that allows developers to work with data using a variety of standard APIs, such as SQL, MongoDB, Graph, and Azure Table storage.
 
-Connect to Cosmos DB using Spring Data and CosmosDB libraries.
 
 === Dependency Setup
 
@@ -32,15 +31,15 @@ NOTE: If you choose to use a security principal to authenticate and authorize wi
 
 |*spring.cloud.azure.cosmos*.database
 |  
-|The CosmosDB database id 
+|The Cosmos DB database id.
 
 |*spring.cloud.azure.cosmos*.endpoint
 |  
-|Uri to connect CosmosDB 
+|Uri to connect Cosmos DB.
 
 |*spring.cloud.azure.cosmos*.key
 |  
-|PrivateKey to connect CosmosDB 
+|Private key to connect Cosmos DB.
 
 |*spring.cloud.azure.cosmos*.credential.client-certificate-password
 |
@@ -76,7 +75,7 @@ NOTE: If you choose to use a security principal to authenticate and authorize wi
 
 |*spring.cloud.azure.cosmos*.consistency-level
 |
-| link:https://docs.microsoft.com/azure/cosmos-db/consistency-levels[Consistency levels] in Azure Cosmos DB
+| link:https://docs.microsoft.com/azure/cosmos-db/consistency-levels[Consistency levels] in Azure Cosmos DB.
 |===
 
 
@@ -264,5 +263,5 @@ Autowired UserRepository interface, then can do save, delete and find operations
 Please refer to link:https://github.com/Azure-Samples/azure-spring-boot-samples/tree/spring-cloud-azure_{project-version}/cosmos[azure-spring-boot-samples] for more details.
 
 
-Besides, using this Azure Cosmos DB Spring Boot Starter, you can directly use Spring Data for Azure Cosmos DB package for more complex scenarios. Please refer to link:https://github.com/Azure/azure-sdk-for-java/tree/spring-cloud-azure-dependencies_{project-version}/sdk/cosmos/azure-spring-data-cosmos[Spring Data for Azure Cosmos DB] for more details.
+Apart from using the `spring-cloud-azure-starter-data-cosmos` library, you can directly use `azure-spring-data-cosmos` library for more complex scenarios. Please refer to link:https://github.com/Azure/azure-sdk-for-java/tree/spring-cloud-azure-dependencies_{project-version}/sdk/cosmos/azure-spring-data-cosmos[Spring Data for Azure Cosmos DB] for more details.