Adding documentation for appconfig

sdk/appconfiguration/app-configuration/review/app-configuration.api.md

@@ -16,23 +16,16 @@ export type AddConfigurationSettingOptions = ModelConfigurationClientCreateOrUpd
 // @public (undocumented)
 export type AddConfigurationSettingsResponse = ModelCreateOrUpdateConfigurationSettingResponse;
 
-// @public (undocumented)
+// @public
 export class AppConfigurationClient {
     constructor(connectionString: string);
     constructor(uri: string, credential: TokenCredential);
-    // (undocumented)
     addConfigurationSetting(key: string, configSettings: AddConfigurationSettingConfig, options?: AddConfigurationSettingOptions): Promise<AddConfigurationSettingsResponse>;
-    // (undocumented)
     deleteConfigurationSetting(key: string, options: DeleteConfigurationSettingOptions): Promise<DeleteConfigurationSettingResponse>;
-    // (undocumented)
     getConfigurationSetting(key: string, options?: GetConfigurationSettingOptions): Promise<GetConfigurationSettingResponse>;
-    // (undocumented)
     listConfigurationSettings(options?: ListConfigurationSettingsOptions): Promise<ListConfigurationSettingsResponse>;
-    // (undocumented)
     listRevisions(options?: ListRevisionsOptions): Promise<ListRevisionsResponse>;
-    // (undocumented)
     setConfigurationSetting(key: string, configSettings: SetConfigurationSettingConfig, options?: SetConfigurationSettingOptions): Promise<SetConfigurationSettingResponse>;
-    // (undocumented)
     updateConfigurationSetting(key: string, configSettings: UpdateConfigurationSettingConfig, options?: UpdateConfigurationSettingOptions): Promise<UpdateConfigurationSettingResponse>;
 }
 
@@ -50,7 +43,6 @@ export type DeleteConfigurationSettingResponse = ModelDeleteConfigurationSetting
 
 // @public (undocumented)
 export interface ETagOption {
-    // (undocumented)
     etag?: string;
 }
 

sdk/appconfiguration/app-configuration/src/appConfigCredential.ts

@@ -1,6 +1,10 @@
 import * as crypto from "crypto";
 import { ServiceClientCredentials, WebResource, URLBuilder } from "@azure/core-http";
 
+/**
+ * @internal
+ * @ignore
+ */
 export class AppConfigCredential implements ServiceClientCredentials {
   private credential: string;
   private secret: string;
@@ -10,6 +14,12 @@ export class AppConfigCredential implements ServiceClientCredentials {
     this.secret = secret;
   }
 
+  /**
+   * Signs a request with the values provided in the credential and secret parameter.
+   *
+   * @param {WebResource} webResource The WebResource to be signed.
+   * @returns {Promise<WebResource>} The signed request object.
+   */
   signRequest(webResource: WebResource): Promise<WebResource> {
     const verb = webResource.method.toUpperCase()
     const utcNow = new Date().toUTCString();
@@ -29,8 +39,8 @@ export class AppConfigCredential implements ServiceClientCredentials {
     const decodedSecret = Buffer.from(this.secret, "base64");
     var signature =
       crypto.createHmac("sha256", decodedSecret)
-      .update(stringToSign)
-      .digest("base64");
+        .update(stringToSign)
+        .digest("base64");
 
     webResource.headers.set("x-ms-date", utcNow);
     webResource.headers.set("x-ms-content-sha256", contentHash);

sdk/appconfiguration/app-configuration/src/index.ts

@@ -47,31 +47,52 @@ const deserializationContentTypes = {
 }
 
 export interface ETagOption {
+  /**
+   * Entity tag (etag) of the object
+   */
   etag?: string;
 }
 
 export type AddConfigurationSettingConfig = Pick<ModelConfigurationSetting, Exclude<keyof ModelConfigurationSetting, "key">>;
 export type AddConfigurationSettingOptions = ModelConfigurationClientCreateOrUpdateConfigurationSettingOptionalParams;
 export type AddConfigurationSettingsResponse = ModelCreateOrUpdateConfigurationSettingResponse;
+
 export type DeleteConfigurationSettingOptions = ModelConfigurationClientDeleteConfigurationSettingOptionalParams & ETagOption;
 export type DeleteConfigurationSettingResponse = ModelDeleteConfigurationSettingResponse;
+
 export type GetConfigurationSettingOptions = ModelConfigurationClientGetConfigurationSettingOptionalParams;
 export type GetConfigurationSettingResponse = ModelGetConfigurationSettingResponse;
+
 export type ListConfigurationSettingsOptions = ModelConfigurationClientListConfigurationSettingsOptionalParams;
 export type ListConfigurationSettingsResponse = ModelListConfigurationSettingsResponse;
+
 export type ListRevisionsOptions = ModelConfigurationClientListRevisionsOptionalParams;
 export type ListRevisionsResponse = ModelListRevisionsResponse;
+
 export type SetConfigurationSettingConfig = Pick<ModelConfigurationSetting, Exclude<keyof ModelConfigurationSetting, "key">>;
 export type SetConfigurationSettingOptions = ModelConfigurationClientCreateOrUpdateConfigurationSettingOptionalParams;
 export type SetConfigurationSettingResponse = ModelCreateOrUpdateConfigurationSettingResponse;
+
 export type UpdateConfigurationSettingConfig = Pick<ModelConfigurationSetting, Exclude<keyof ModelConfigurationSetting, "key">>;
 export type UpdateConfigurationSettingOptions = ModelConfigurationClientCreateOrUpdateConfigurationSettingOptionalParams;
 export type UpdateConfigurationSettingResponse = ModelCreateOrUpdateConfigurationSettingResponse;
 
+/**
+ * Client for the Azure App Configuration service.
+ */
 export class AppConfigurationClient {
   private client: ConfigurationClient;
 
+  /**
+   * Initializes a new instance of the AppConfigurationClient class.
+   * @param connectionString Connection string needed for a client to connect to Azure.
+   */
   constructor(connectionString: string);
+  /**
+   * Initializes a new instance of the AppConfigurationClient class.
+   * @param uri The base URI for the Azure service
+   * @param credential The credentials to use for authentication.
+   */
   constructor(uri: string, credential: TokenCredential);
   constructor(uriOrConnectionString: string, credential?: TokenCredential) {
     const regexMatch = uriOrConnectionString.match(ConnectionStringRegex);
@@ -91,6 +112,18 @@ export class AppConfigurationClient {
     }
   }
 
+  /**
+   * Add a setting into the Azure App Configuration service, failing if it 
+   * already exists.
+   * 
+   * Example usage:
+   * ```ts
+   * const result = await client.addConfigurationSetting("MyKey", { label: "MyLabel", value: "MyValue" });
+   * ```
+   * @param key The name of the key.
+   * @param configSettings A configuration value.
+   * @param options Optional parameters for the request.
+   */
   addConfigurationSetting(key: string, configSettings: AddConfigurationSettingConfig, options: AddConfigurationSettingOptions = {}): Promise<AddConfigurationSettingsResponse> {
     // add the custom header if-none-match=* to only add the key-value if it doesn't already exist
     // create a copy of the options to avoid modifying the user's options
@@ -105,6 +138,16 @@ export class AppConfigurationClient {
     return this.client.createOrUpdateConfigurationSetting(configSettings, key, options);
   }
 
+  /**
+   * Delete a setting from the Azure App Configuration service
+   * 
+   * Example usage:
+   * ```ts
+   * const deletedSetting = await client.deleteConfigurationSetting("MyKey", { label: "MyLabel" });
+   * ```
+   * @param key The name of the key.
+   * @param options Optional parameters for the request.
+   */
   deleteConfigurationSetting(key: string, options: DeleteConfigurationSettingOptions): Promise<DeleteConfigurationSettingResponse> {
     // hoist the etag into a custom header to ensure this update fails if the setting has been updated
     options = { ...options };
@@ -118,18 +161,58 @@ export class AppConfigurationClient {
     return this.client.deleteConfigurationSetting(key, options);
   }
 
+  /**
+   * Gets a setting from the Azure App Configuration service.
+   * 
+   * Example code:
+   * ```ts
+   * const setting = await client.getConfigurationSetting("MyKey", { label: "MyLabel" });
+   * ```
+   * @param key The name of the key.
+   * @param options Optional parameters for the request.
+   */
   getConfigurationSetting(key: string, options?: GetConfigurationSettingOptions): Promise<GetConfigurationSettingResponse> {
     return this.client.getConfigurationSetting(key, options);
   }
 
+  /**
+   * Lists settings from the Azure App Configuration service, optionally filtered by label, 
+   * accept date time or name.
+   * 
+   * Example code:
+   * ```ts
+   * const allSettingsWithLabel = await client.listConfigurationSettings({ label: "MyLabel" });
+   * ```
+   * @param options Optional parameters for the request.
+   */
   listConfigurationSettings(options?: ListConfigurationSettingsOptions): Promise<ListConfigurationSettingsResponse> {
     return this.client.listConfigurationSettings(options);
   }
 
+  /**
+   * Lists revisions of a set of keys within the Azure App Configuration service.
+   * 
+   * Example code:
+   * ```ts
+   * const revisionsForMyKey = await client.listRevisions({ key: ["MyKey"] });
+   * ```
+   * @param options Optional parameters for the request.
+   */
   listRevisions(options?: ListRevisionsOptions): Promise<ListRevisionsResponse> {
     return this.client.listRevisions(options);
   }
 
+  /**
+   * Sets the value of a key in the Azure App Configuration service, allowing for an optional etag.
+   * @param key The name of the key.
+   * @param configSettings A configuration value.
+   * @param options Optional parameters for the request.
+   * 
+   * Example code:
+   * ```ts
+   * let result = await client.setConfigurationSetting("MyKey", { value: "MyValue" });
+   * ```
+   */
   setConfigurationSetting(key: string, configSettings: SetConfigurationSettingConfig, options: SetConfigurationSettingOptions = {}): Promise<SetConfigurationSettingResponse> {
     // hoist the etag into a custom header to ensure this update fails if the setting has been updated
     options = { ...options };
@@ -148,6 +231,17 @@ export class AppConfigurationClient {
     return this.client.createOrUpdateConfigurationSetting(configSettings, key, { ...options, customHeaders });
   }
 
+  /**
+   * Updates the value of a key in the Azure App Configuration service.
+   * 
+   * Example code:
+   * ```ts
+   * await client.updateConfigurationSetting("MyKey", { label: "MyLabel", value: "MyValue" });
+   * ```
+   * @param key The name of the key.
+   * @param configSettings A configuration value.
+   * @param options Optional parameters for the request.
+   */
   async updateConfigurationSetting(key: string, configSettings: UpdateConfigurationSettingConfig, options: UpdateConfigurationSettingOptions = {}): Promise<UpdateConfigurationSettingResponse> {
     // retrieve existing configuration, and populate configSettings for missing fields that aren't null
     const existingConfigurationSettings = await this.getConfigurationSetting(key, {
@@ -156,6 +250,7 @@ export class AppConfigurationClient {
     });
 
     const updateConfigSettings = { ...configSettings };
+
     if (typeof updateConfigSettings.value === "undefined") {
       updateConfigSettings.value = existingConfigurationSettings.value;
     }

sdk/appconfiguration/app-configuration/test/index.spec.ts

@@ -35,10 +35,19 @@ describe("AppConfigurationClient", () => {
   });
 
   describe("addConfigurationSetting", () => {
+    it("sample works", async () => {
+      const key = `addConfigSample-${Date.now()}`;
+      let result = await client.setConfigurationSetting(key, {
+        value: "MyValue"
+      });
+
+      assert.equal(key, result.key);
+    });
+
     it("adds a configuration setting", async () => {
       const key = `addConfigTest-${Date.now()}`;
-      const label = "test";
-      const value = "foo";
+      const label = "MyLabel";
+      const value = "MyValue";
       const result = await client.addConfigurationSetting(key, { label, value });
 
       settings.push({ key, label });
@@ -73,8 +82,8 @@ describe("AppConfigurationClient", () => {
   describe("deleteConfigurationSetting", () => {
     it("deletes an existing configuration setting", async () => {
       const key = `deleteConfigTest-${Date.now()}`;
-      const label = "test";
-      const value = "foo";
+      const label = "MyLabel";
+      const value = "MyValue";
 
       // create configuration
       const result = await client.addConfigurationSetting(key, { label, value });
@@ -251,6 +260,21 @@ describe("AppConfigurationClient", () => {
 
       assert.equal(result.length, 2);
     });
+
+    it("sample code works", async () => {
+      const key = `listRevisionsSample-${Date.now()}`;
+
+      // create a new setting
+      await client.addConfigurationSetting(key, { value: "foo1" });
+
+      // update it with a new value
+      await client.setConfigurationSetting(key, { value: "foo2" });
+
+      // retrieves all revisions matching that label
+      const result = await client.listRevisions({ key: [key] });
+
+      assert.equal(result.length, 2);
+    })
   });
 
   describe("setConfigurationSetting", () => {