Skip to content

Commit

Permalink
docs(iam): mark required params as required in docstring (via synth) (#…
Browse files Browse the repository at this point in the history 
…10006)
  • Loading branch information
@yoshi-automation @busunkim96
yoshi-automation authored and busunkim96 committed Dec 20, 2019
1 parent 13bd849 commit 4d70df3
Show file tree
Hide file tree
Showing 6 changed files with 3,616 additions and 108 deletions.
56 changes: 36 additions & 20 deletions iam/google/cloud/iam_credentials_v1/gapic/iam_credentials_client.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -234,10 +234,12 @@ def generate_access_token(
>>> response = client.generate_access_token(name, scope)
Args:
name (str): The resource name of the service account for which the credentials are
requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
scope (list[str]): Code to identify the scopes to be included in the OAuth 2.0 access token.
name (str): Required. The resource name of the service account for which the
credentials are requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
scope (list[str]): Required. Code to identify the scopes to be included in the OAuth 2.0 access token.
See https://developers.google.com/identity/protocols/googlescopes for more
information.
At least one value required.
Expand All @@ -249,7 +251,9 @@ def generate_access_token(
that is specified in the ``name`` field of the request.
The delegates must have the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
lifetime (Union[dict, ~google.cloud.iam_credentials_v1.types.Duration]): The desired lifetime duration of the access token in seconds.
Must be set to a value less than or equal to 3600 (1 hour). If a value is
not specified, the token's lifetime will be set to a default value of one
Expand Down Expand Up @@ -333,10 +337,12 @@ def generate_id_token(
>>> response = client.generate_id_token(name, audience)
Args:
name (str): The resource name of the service account for which the credentials are
requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
audience (str): The audience for the token, such as the API or account that this token
name (str): Required. The resource name of the service account for which the
credentials are requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
audience (str): Required. The audience for the token, such as the API or account that this token
grants access to.
delegates (list[str]): The sequence of service accounts in a delegation chain. Each service
account must be granted the ``roles/iam.serviceAccountTokenCreator``
Expand All @@ -346,7 +352,9 @@ def generate_id_token(
that is specified in the ``name`` field of the request.
The delegates must have the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
include_email (bool): Include the service account email in the token. If set to ``true``, the
token will contain ``email`` and ``email_verified`` claims.
retry (Optional[google.api_core.retry.Retry]): A retry object used
Expand Down Expand Up @@ -427,10 +435,12 @@ def sign_blob(
>>> response = client.sign_blob(name, payload)
Args:
name (str): The resource name of the service account for which the credentials are
requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
payload (bytes): The bytes to sign.
name (str): Required. The resource name of the service account for which the
credentials are requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
payload (bytes): Required. The bytes to sign.
delegates (list[str]): The sequence of service accounts in a delegation chain. Each service
account must be granted the ``roles/iam.serviceAccountTokenCreator``
role on its next service account in the chain. The last service account
Expand All @@ -439,7 +449,9 @@ def sign_blob(
that is specified in the ``name`` field of the request.
The delegates must have the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
retry (Optional[google.api_core.retry.Retry]): A retry object used
to retry requests. If ``None`` is specified, requests will
be retried using a default configuration.
Expand Down Expand Up @@ -515,10 +527,12 @@ def sign_jwt(
>>> response = client.sign_jwt(name, payload)
Args:
name (str): The resource name of the service account for which the credentials are
requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``.
payload (str): The JWT payload to sign: a JSON object that contains a JWT Claims Set.
name (str): Required. The resource name of the service account for which the
credentials are requested, in the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
payload (str): Required. The JWT payload to sign: a JSON object that contains a JWT Claims Set.
delegates (list[str]): The sequence of service accounts in a delegation chain. Each service
account must be granted the ``roles/iam.serviceAccountTokenCreator``
role on its next service account in the chain. The last service account
Expand All @@ -527,7 +541,9 @@ def sign_jwt(
that is specified in the ``name`` field of the request.
The delegates must have the following format:
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``
``projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}``. The ``-``
wildcard character is required; replacing it with a project ID is
invalid.
retry (Optional[google.api_core.retry.Retry]): A retry object used
to retry requests. If ``None`` is specified, requests will
be retried using a default configuration.
Expand Down
85 changes: 60 additions & 25 deletions iam/google/cloud/iam_credentials_v1/proto/common.proto
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright 2018 Google LLC
// Copyright 2019 Google LLC.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
Expand All @@ -11,11 +11,14 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

syntax = "proto3";

package google.iam.credentials.v1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

Expand All @@ -24,12 +27,22 @@ option go_package = "google.golang.org/genproto/googleapis/iam/credentials/v1;cr
option java_multiple_files = true;
option java_outer_classname = "IAMCredentialsCommonProto";
option java_package = "com.google.cloud.iam.credentials.v1";
option (google.api.resource_definition) = {
type: "iam.googleapis.com/ServiceAccount"
pattern: "projects/{project}/serviceAccounts/{service_account}"
};

message GenerateAccessTokenRequest {
// The resource name of the service account for which the credentials
// Required. The resource name of the service account for which the credentials
// are requested, in the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
string name = 1;
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "iam.googleapis.com/ServiceAccount"
}
];

// The sequence of service accounts in a delegation chain. Each service
// account must be granted the `roles/iam.serviceAccountTokenCreator` role
Expand All @@ -39,14 +52,15 @@ message GenerateAccessTokenRequest {
// request.
//
// The delegates must have the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
repeated string delegates = 2;

// Code to identify the scopes to be included in the OAuth 2.0 access token.
// Required. Code to identify the scopes to be included in the OAuth 2.0 access token.
// See https://developers.google.com/identity/protocols/googlescopes for more
// information.
// At least one value required.
repeated string scope = 4;
repeated string scope = 4 [(google.api.field_behavior) = REQUIRED];

// The desired lifetime duration of the access token in seconds.
// Must be set to a value less than or equal to 3600 (1 hour). If a value is
Expand All @@ -65,10 +79,16 @@ message GenerateAccessTokenResponse {
}

message SignBlobRequest {
// The resource name of the service account for which the credentials
// Required. The resource name of the service account for which the credentials
// are requested, in the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
string name = 1;
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "iam.googleapis.com/ServiceAccount"
}
];

// The sequence of service accounts in a delegation chain. Each service
// account must be granted the `roles/iam.serviceAccountTokenCreator` role
Expand All @@ -78,11 +98,12 @@ message SignBlobRequest {
// request.
//
// The delegates must have the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
repeated string delegates = 3;

// The bytes to sign.
bytes payload = 5;
// Required. The bytes to sign.
bytes payload = 5 [(google.api.field_behavior) = REQUIRED];
}

message SignBlobResponse {
Expand All @@ -94,10 +115,16 @@ message SignBlobResponse {
}

message SignJwtRequest {
// The resource name of the service account for which the credentials
// Required. The resource name of the service account for which the credentials
// are requested, in the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
string name = 1;
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "iam.googleapis.com/ServiceAccount"
}
];

// The sequence of service accounts in a delegation chain. Each service
// account must be granted the `roles/iam.serviceAccountTokenCreator` role
Expand All @@ -107,11 +134,12 @@ message SignJwtRequest {
// request.
//
// The delegates must have the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
repeated string delegates = 3;

// The JWT payload to sign: a JSON object that contains a JWT Claims Set.
string payload = 5;
// Required. The JWT payload to sign: a JSON object that contains a JWT Claims Set.
string payload = 5 [(google.api.field_behavior) = REQUIRED];
}

message SignJwtResponse {
Expand All @@ -123,10 +151,16 @@ message SignJwtResponse {
}

message GenerateIdTokenRequest {
// The resource name of the service account for which the credentials
// Required. The resource name of the service account for which the credentials
// are requested, in the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`.
string name = 1;
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
string name = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "iam.googleapis.com/ServiceAccount"
}
];

// The sequence of service accounts in a delegation chain. Each service
// account must be granted the `roles/iam.serviceAccountTokenCreator` role
Expand All @@ -136,12 +170,13 @@ message GenerateIdTokenRequest {
// request.
//
// The delegates must have the following format:
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`
// `projects/-/serviceAccounts/{ACCOUNT_EMAIL_OR_UNIQUEID}`. The `-` wildcard
// character is required; replacing it with a project ID is invalid.
repeated string delegates = 2;

// The audience for the token, such as the API or account that this token
// Required. The audience for the token, such as the API or account that this token
// grants access to.
string audience = 3;
string audience = 3 [(google.api.field_behavior) = REQUIRED];

// Include the service account email in the token. If set to `true`, the
// token will contain `email` and `email_verified` claims.
Expand Down
Loading

0 comments on commit 4d70df3

Please sign in to comment.