docs: various documentation clarifications

Google APIs · copybara-github · commit 4657bfafc269 · 2025-04-15T13:32:21.000-07:00
PiperOrigin-RevId: 748001251
diff --git a/google/cloud/secrets/v1beta1/resources.proto b/google/cloud/secrets/v1beta1/resources.proto
@@ -20,7 +20,6 @@ import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/protobuf/timestamp.proto";
 
-option cc_enable_arenas = true;
 option csharp_namespace = "Google.Cloud.SecretManager.V1Beta1";
 option go_package = "cloud.google.com/go/secrets/apiv1beta1/secretspb;secretspb";
 option java_multiple_files = true;
@@ -30,30 +29,36 @@ option objc_class_prefix = "GSM";
 option php_namespace = "Google\\Cloud\\SecretManager\\V1beta1";
 option ruby_package = "Google::Cloud::SecretManager::V1beta1";
 
-// A [Secret][google.cloud.secrets.v1beta1.Secret] is a logical secret whose value and versions can
-// be accessed.
+// A [Secret][google.cloud.secrets.v1beta1.Secret] is a logical secret whose
+// value and versions can be accessed.
 //
-// A [Secret][google.cloud.secrets.v1beta1.Secret] is made up of zero or more [SecretVersions][google.cloud.secrets.v1beta1.SecretVersion] that
-// represent the secret data.
+// A [Secret][google.cloud.secrets.v1beta1.Secret] is made up of zero or more
+// [SecretVersions][google.cloud.secrets.v1beta1.SecretVersion] that represent
+// the secret data.
 message Secret {
   option (google.api.resource) = {
     type: "secretmanager.googleapis.com/Secret"
     pattern: "projects/{project}/secrets/{secret}"
   };
 
-  // Output only. The resource name of the [Secret][google.cloud.secrets.v1beta1.Secret] in the format `projects/*/secrets/*`.
+  // Output only. The resource name of the
+  // [Secret][google.cloud.secrets.v1beta1.Secret] in the format
+  // `projects/*/secrets/*`.
   string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Required. Immutable. The replication policy of the secret data attached to the [Secret][google.cloud.secrets.v1beta1.Secret].
+  // Required. Immutable. The replication policy of the secret data attached to
+  // the [Secret][google.cloud.secrets.v1beta1.Secret].
   //
   // The replication policy cannot be changed after the Secret has been created.
   Replication replication = 2 [
     (google.api.field_behavior) = IMMUTABLE,
     (google.api.field_behavior) = REQUIRED
   ];
 
-  // Output only. The time at which the [Secret][google.cloud.secrets.v1beta1.Secret] was created.
-  google.protobuf.Timestamp create_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // Output only. The time at which the
+  // [Secret][google.cloud.secrets.v1beta1.Secret] was created.
+  google.protobuf.Timestamp create_time = 3
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // The labels assigned to this Secret.
   //
@@ -76,79 +81,97 @@ message SecretVersion {
     pattern: "projects/{project}/secrets/{secret}/versions/{secret_version}"
   };
 
-  // The state of a [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion], indicating if it can be accessed.
+  // The state of a [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion],
+  // indicating if it can be accessed.
   enum State {
     // Not specified. This value is unused and invalid.
     STATE_UNSPECIFIED = 0;
 
-    // The [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] may be accessed.
+    // The [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] may be
+    // accessed.
     ENABLED = 1;
 
-    // The [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] may not be accessed, but the secret data
-    // is still available and can be placed back into the [ENABLED][google.cloud.secrets.v1beta1.SecretVersion.State.ENABLED]
+    // The [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] may not
+    // be accessed, but the secret data is still available and can be placed
+    // back into the
+    // [ENABLED][google.cloud.secrets.v1beta1.SecretVersion.State.ENABLED]
     // state.
     DISABLED = 2;
 
-    // The [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] is destroyed and the secret data is no longer
-    // stored. A version may not leave this state once entered.
+    // The [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] is
+    // destroyed and the secret data is no longer stored. A version may not
+    // leave this state once entered.
     DESTROYED = 3;
   }
 
-  // Output only. The resource name of the [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] in the
-  // format `projects/*/secrets/*/versions/*`.
+  // Output only. The resource name of the
+  // [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] in the format
+  // `projects/*/secrets/*/versions/*`.
   //
-  // [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] IDs in a [Secret][google.cloud.secrets.v1beta1.Secret] start at 1 and
-  // are incremented for each subsequent version of the secret.
+  // [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] IDs in a
+  // [Secret][google.cloud.secrets.v1beta1.Secret] start at 1 and are
+  // incremented for each subsequent version of the secret.
   string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The time at which the [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] was created.
-  google.protobuf.Timestamp create_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // Output only. The time at which the
+  // [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] was created.
+  google.protobuf.Timestamp create_time = 2
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The time this [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] was destroyed.
-  // Only present if [state][google.cloud.secrets.v1beta1.SecretVersion.state] is
-  // [DESTROYED][google.cloud.secrets.v1beta1.SecretVersion.State.DESTROYED].
-  google.protobuf.Timestamp destroy_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // Output only. The time this
+  // [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion] was destroyed.
+  // Only present if [state][google.cloud.secrets.v1beta1.SecretVersion.state]
+  // is [DESTROYED][google.cloud.secrets.v1beta1.SecretVersion.State.DESTROYED].
+  google.protobuf.Timestamp destroy_time = 3
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The current state of the [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion].
+  // Output only. The current state of the
+  // [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion].
   State state = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // A policy that defines the replication configuration of data.
 message Replication {
-  // A replication policy that replicates the [Secret][google.cloud.secrets.v1beta1.Secret] payload without any
+  // A replication policy that replicates the
+  // [Secret][google.cloud.secrets.v1beta1.Secret] payload without any
   // restrictions.
-  message Automatic {
+  message Automatic {}
 
-  }
-
-  // A replication policy that replicates the [Secret][google.cloud.secrets.v1beta1.Secret] payload into the
-  // locations specified in [Secret.replication.user_managed.replicas][]
+  // A replication policy that replicates the
+  // [Secret][google.cloud.secrets.v1beta1.Secret] payload into the locations
+  // specified in
+  // [Replication.UserManaged.replicas][google.cloud.secrets.v1beta1.Replication.UserManaged.replicas]
   message UserManaged {
-    // Represents a Replica for this [Secret][google.cloud.secrets.v1beta1.Secret].
+    // Represents a Replica for this
+    // [Secret][google.cloud.secrets.v1beta1.Secret].
     message Replica {
       // The canonical IDs of the location to replicate data.
       // For example: `"us-east1"`.
       string location = 1;
     }
 
-    // Required. The list of Replicas for this [Secret][google.cloud.secrets.v1beta1.Secret].
+    // Required. The list of Replicas for this
+    // [Secret][google.cloud.secrets.v1beta1.Secret].
     //
     // Cannot be empty.
     repeated Replica replicas = 1 [(google.api.field_behavior) = REQUIRED];
   }
 
   // The replication policy for this secret.
   oneof replication {
-    // The [Secret][google.cloud.secrets.v1beta1.Secret] will automatically be replicated without any restrictions.
+    // The [Secret][google.cloud.secrets.v1beta1.Secret] will automatically be
+    // replicated without any restrictions.
     Automatic automatic = 1;
 
-    // The [Secret][google.cloud.secrets.v1beta1.Secret] will only be replicated into the locations specified.
+    // The [Secret][google.cloud.secrets.v1beta1.Secret] will only be replicated
+    // into the locations specified.
     UserManaged user_managed = 2;
   }
 }
 
 // A secret payload resource in the Secret Manager API. This contains the
-// sensitive secret data that is associated with a [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion].
+// sensitive secret data that is associated with a
+// [SecretVersion][google.cloud.secrets.v1beta1.SecretVersion].
 message SecretPayload {
   // The secret data. Must be no larger than 64KiB.
   bytes data = 1;
diff --git a/google/cloud/secrets/v1beta1/secretmanager_v1beta1.yaml b/google/cloud/secrets/v1beta1/secretmanager_v1beta1.yaml
@@ -4,22 +4,48 @@ name: secretmanager.googleapis.com
 title: Secret Manager API
 
 apis:
+- name: google.cloud.location.Locations
 - name: google.cloud.secrets.v1beta1.SecretManagerService
 
 documentation:
   summary: |-
     Stores sensitive data such as API keys, passwords, and certificates.
     Provides convenience while improving security.
   overview: Secret Manager Overview
+  rules:
+  - selector: google.cloud.location.Locations.GetLocation
+    description: Gets information about a location.
+
+  - selector: google.cloud.location.Locations.ListLocations
+    description: Lists information about the supported locations for this service.
 
-backend:
+http:
   rules:
-  - selector: 'google.cloud.secrets.v1beta1.SecretManagerService.*'
-    deadline: 10.0
+  - selector: google.cloud.location.Locations.GetLocation
+    get: '/v1beta1/{name=projects/*/locations/*}'
+  - selector: google.cloud.location.Locations.ListLocations
+    get: '/v1beta1/{name=projects/*}/locations'
 
 authentication:
   rules:
+  - selector: google.cloud.location.Locations.GetLocation
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform
+  - selector: google.cloud.location.Locations.ListLocations
+    oauth:
+      canonical_scopes: |-
+        https://www.googleapis.com/auth/cloud-platform
   - selector: 'google.cloud.secrets.v1beta1.SecretManagerService.*'
     oauth:
       canonical_scopes: |-
         https://www.googleapis.com/auth/cloud-platform
+
+publishing:
+  new_issue_uri: https://issuetracker.google.com/issues/new?component=784854&template=1380926
+  documentation_uri: https://cloud.google.com/secret-manager/docs/overview
+  api_short_name: secretmanager
+  github_label: 'api: secretmanager'
+  doc_tag_prefix: secretmanager
+  organization: CLOUD
+  proto_reference_documentation_uri: https://cloud.google.com/secret-manager/docs/reference/rpc
diff --git a/google/cloud/secrets/v1beta1/service.proto b/google/cloud/secrets/v1beta1/service.proto
