CyberCoveLLC/threshold
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

internal/proto: improvements to OpenAPIv2 spec (#4555)

Browse Source 
* internal/gen: better API docs

Add various pieces of metadata that can be used by the API docs renderer.
Improve the service labels by specifying explicit tags.
Specify error responses. Specify version at generation time.

* internal/gen: add better errors

The default error entry is now used to cover all errors, as
adding a new error for every possible status code was a bit much.
This also properly includes the real error type now!

* Add various pieces of metadata that can be used by the API docs renderer. Improve the service labels by specifying explicit tags.

* make auth method API docs

* make API docs better

* make auth methods API docs nicer

* internal/gen: better attribute examples

Replace Output Only comments with a field behavior annotation in accounts.
Mark some fields as required.
Add elaborate description for attributes.

* Make API docs better

* Make API docs better

* Make API docs better

* internal/proto: regenerate files

* internal/proto: finish off account service

* Make API docs better

* internal/proto: add better API docs for aliases

* Tidy up service descriptions

* Added description for Boundary controller  API doc

* internal/gen: add better API intro

Copy parts of the API docs into the description

* sdk: add openapi dependency

* internal/gen: move global API doc to separate file

* internal/gen: remove required annotations

Unfortunately, while these help with the creating of resources, they still
appear required in contexts where they are not, such as when
updating a resource.

* Review comments

---------

Co-authored-by: jigar-hashicorp <jigar.shah@hashicorp.com>
Co-authored-by: Isaac Christian (he/him) <112639904+isaacchristian@users.noreply.github.com>
This commit is contained in:
Johan Brandhorst-Satzkornjigar-hashicorpIsaac Christian
 authored and GitHub committed 2024-04-08 13:55:17 -07:00
1 parent b908e7b9da
commit 6b53766aa6
69 files changed
+4339 -1803
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

internal/proto/controller/api/resources/accounts/v1/account.proto
+100 -44
View File
@@ -7,20 +7,22 @@ package controller.api.resources.accounts.v1;
import "controller/api/resources/scopes/v1/scope.proto";
import "controller/custom_options/v1/options.proto";
import "google/api/field_behavior.proto";
import "google/api/visibility.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
option go_package = "github.com/hashicorp/boundary/sdk/pbs/controller/api/resources/accounts;accounts";
// Account contains all fields related to an Account resource
// Account contains all fields related to an account resource
message Account {
// Output only. The ID of the Account.
string id = 10; // @gotags: `class:"public" eventstream:"observation"`
// The ID of the account.
string id = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public" eventstream:"observation"`
// Output only. Scope information for the Account.
resources.scopes.v1.ScopeInfo scope = 20;
// Scope information for the account.
resources.scopes.v1.ScopeInfo scope = 20 [(google.api.field_behavior) = OUTPUT_ONLY];
// Optional name for identification purposes.
google.protobuf.StringValue name = 30 [
@@ -40,30 +42,72 @@ message Account {
}
]; // @gotags: `class:"public"`
// Output only. The time this resource was created.
google.protobuf.Timestamp created_time = 50 [json_name = "created_time"]; // @gotags: `class:"public" eventstream:"observation"`
// The time this resource was created.
google.protobuf.Timestamp created_time = 50 [
json_name = "created_time",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public" eventstream:"observation"`
// Output only. The time this resource was last updated.
google.protobuf.Timestamp updated_time = 60 [json_name = "updated_time"]; // @gotags: `class:"public" eventstream:"observation"`
// The time this resource was last updated.
google.protobuf.Timestamp updated_time = 60 [
json_name = "updated_time",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public" eventstream:"observation"`
// Version is used in mutation requests, after the initial creation, to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
// The mutation fails if the version does not match the latest known good version.
// Version is not required when you create an account.
uint32 version = 70; // @gotags: `class:"public"`
// The type of this Account.
// The type of this account. If you do not set an account type, Boundary infers it from the type of the auth method.
string type = 80; // @gotags: `class:"public" eventstream:"observation"`
// The ID of the Auth Method that is associated with this Account.
// The ID of the auth method that is associated with this account.
string auth_method_id = 90 [
json_name = "auth_method_id",
(custom_options.v1.subtype_source_id) = true
]; // @gotags: `class:"public" eventstream:"observation"`
oneof attrs {
// The attributes that are applicable for the specific Account type.
// The attributes that are applicable for the specific account type.
google.protobuf.Struct attributes = 100 [
(custom_options.v1.generate_sdk_option) = true,
(custom_options.v1.subtype) = "default"
(custom_options.v1.subtype) = "default",
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "{\"login_name\": \"login_name\"}",
description:
"The attributes that are applicable for the specific account type. "
"The schema of this field depends on the type of the auth method "
"that you create the account in.\n"
"For password auth methods, the parameters are:\n"
"```json\n"
"{\n"
" \"login_name\": \"login_name\",\n"
" \"password\": \"password\"\n"
"}\n"
"```\n"
"For OIDC auth methods, the parameters are:\n"
"```json\n"
"{\n"
" \"issuer\": \"issuer\",\n"
" \"subject\": \"subject\",\n"
" \"full_name\": \"full_name\",\n"
" \"email\": \"email\",\n"
" \"token_claims\": {},\n"
" \"userinfo_claims\": {}\n"
"}\n"
"```\n"
"For LDAP auth methods, the parameters are:\n"
"```json\n"
"{\n"
" \"login_name\": \"login_name\",\n"
" \"full_name\": \"full_name\",\n"
" \"email\": \"email\",\n"
" \"dn\": \"dn\",\n"
" \"member_of_groups\": [\"member_of_groups\"]\n"
"}\n"
"```\n"
}
];
PasswordAccountAttributes password_account_attributes = 101 [
(google.api.field_visibility).restriction = "INTERNAL",
@@ -82,16 +126,22 @@ message Account {
];
}
// Output only. managed_group_ids indicates IDs of the managed groups that currently contain this account
repeated string managed_group_ids = 110 [json_name = "managed_group_ids"]; // @gotags: `class:"public" eventstream:"observation"`
// Indicates the IDs of the managed groups that currently contain this account
repeated string managed_group_ids = 110 [
json_name = "managed_group_ids",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public" eventstream:"observation"`
// Output only. The available actions on this resource for this user.
repeated string authorized_actions = 300 [json_name = "authorized_actions"]; // @gotags: `class:"public"`
// The available actions on this resource for this user.
repeated string authorized_actions = 300 [
json_name = "authorized_actions",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public"`
}
// Attributes associated only with Accounts with type "password".
// Attributes associated only with accounts with type "password".
message PasswordAccountAttributes {
// The login name of this Account. This is unique per Auth Method.
// The login name of this account. This is unique per auth method.
string login_name = 10 [
json_name = "login_name",
(custom_options.v1.generate_sdk_option) = true,
@@ -101,11 +151,11 @@ message PasswordAccountAttributes {
}
]; // @gotags: `class:"sensitive"`
// The password for this Account.
// The password for this account.
google.protobuf.StringValue password = 20 [(custom_options.v1.generate_sdk_option) = true]; // @gotags: `class:"secret"`
}
// Attributes associated only with Accounts with type "oidc".
// Attributes associated only with accounts with type "oidc".
message OidcAccountAttributes {
// issuer is a case sensitive URL that maps to the OIDC iss claim.
// This value is immutable after creation time.
@@ -121,24 +171,27 @@ message OidcAccountAttributes {
(custom_options.v1.generate_sdk_option) = true
]; // @gotags: `class:"public"`
// Output only. full_name is a string that maps to the OIDC name claim.
string full_name = 100 [json_name = "full_name"]; // @gotags: `class:"public"`
// A string that maps to the OIDC name claim.
string full_name = 100 [
json_name = "full_name",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public"`
// Output only. email is a string that maps to the OIDC email claim.
string email = 110; // @gotags: `class:"public"`
// A string that maps to the OIDC email claim.
string email = 110 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public"`
// Output only. token_claims are the marshaled claims from the token.
google.protobuf.Struct token_claims = 120;
// The marshaled claims from the token.
google.protobuf.Struct token_claims = 120 [(google.api.field_behavior) = OUTPUT_ONLY];
// Output only. userinfo_claims are the marshaled claims from userinfo.
google.protobuf.Struct userinfo_claims = 130;
// The marshaled claims from userinfo.
google.protobuf.Struct userinfo_claims = 130 [(google.api.field_behavior) = OUTPUT_ONLY];
}
// Attributes associated only with Accounts with type "ldap".
// Attributes associated only with accounts with type "ldap".
message LdapAccountAttributes {
// login_name of the authenticated user. This is the login_name (or username)
// login_name of the authenticated user. This is the login_name (or username)
// entered by the user when authenticating (typically the uid or cn
// attribute). Account login names must be lower case.
// attribute). Account login names must be lower case.
string login_name = 100 [
json_name = "login_name",
(custom_options.v1.generate_sdk_option) = true,
@@ -148,24 +201,27 @@ message LdapAccountAttributes {
}
]; // @gotags: `class:"sensitive"`
// Output only. full_name is a string that maps to the name attribute for the
// authenticated user. This attribute is updated every time a user
// A string that maps to the name attribute for the
// authenticated user. This attribute is updated every time a user
// successfully authenticates.
string full_name = 110 [json_name = "full_name"]; // @gotags: `class:"sensitive"`
string full_name = 110 [
json_name = "full_name",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"sensitive"`
// Output only. email is a string that maps to the email address attribute for
// the authenticated user. This attribute is updated every time a user
// A string that maps to the email address attribute for
// the authenticated user. This attribute is updated every time a user
// successfully authenticates.
string email = 120; // @gotags: `class:"sensitive"`
string email = 120 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"sensitive"`
// Output only. dn is the distinguished name authenticated user's entry. Will
// be null until the user's first successful authentication. This attribute
// The distinguished name authenticated user's entry. Will
// be null until the user's first successful authentication. This attribute
// is updated every time a user successfully authenticates.
string dn = 130; // @gotags: `class:"public"`
string dn = 130 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public"`
// Output only. member_of_groups are the json marshalled groups the
// The json marshalled groups the
// authenticated user is a member of. Will be null until the user's first
// successful authentication. This attribute is updated every time a user
// successfully authenticates.
repeated string member_of_groups = 140; // @gotags: `class:"public"`
repeated string member_of_groups = 140 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public"`
}
internal/proto/controller/api/resources/aliases/v1/alias.proto
+44 -18
View File
@@ -7,23 +7,25 @@ package controller.api.resources.aliases.v1;
import "controller/api/resources/scopes/v1/scope.proto";
import "controller/custom_options/v1/options.proto";
import "google/api/field_behavior.proto";
import "google/api/visibility.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
option go_package = "github.com/hashicorp/boundary/sdk/pbs/controller/api/resources/aliases;aliases";
// Alias contains all fields related to an Alias resource
// Alias contains all fields related to an alias resource
message Alias {
// Output only. The ID of the Alias.
string id = 10; // @gotags: `class:"public" eventstream:"observation"`
// The ID of the alias.
string id = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public" eventstream:"observation"`
// The ID of the scope of which this Alias is a part.
// The ID of the scope of which this alias is a part.
string scope_id = 20 [json_name = "scope_id"]; // @gotags: `class:"public" eventstream:"observation"`
// Output only. Scope information for this Alias.
resources.scopes.v1.ScopeInfo scope = 30;
// Scope information for this alias.
resources.scopes.v1.ScopeInfo scope = 30 [(google.api.field_behavior) = OUTPUT_ONLY];
// Optional user-set name for identification purposes.
google.protobuf.StringValue name = 40 [
@@ -43,17 +45,24 @@ message Alias {
}
]; // @gotags: `class:"public"`
// Output only. The time this resource was created.
google.protobuf.Timestamp created_time = 60 [json_name = "created_time"]; // @gotags: `class:"public" eventstream:"observation"`
// The time this resource was created.
google.protobuf.Timestamp created_time = 60 [
json_name = "created_time",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public" eventstream:"observation"`
// Output only. The time this resource was last updated.
google.protobuf.Timestamp updated_time = 70 [json_name = "updated_time"]; // @gotags: `class:"public" eventstream:"observation"`
// The time this resource was last updated.
google.protobuf.Timestamp updated_time = 70 [
json_name = "updated_time",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public" eventstream:"observation"`
// Version is used in mutation requests, after the initial creation, to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
// The mutation fails if the version does not match the latest known good version.
// Version is not required when you create an alias.
uint32 version = 80; // @gotags: `class:"public"`
// Required value of the alias. This is the value referenced by the user that
// Value of the alias. This is the value referenced by the user that
// is resolved to the destination id.
string value = 90 [
(custom_options.v1.generate_sdk_option) = true,
@@ -63,7 +72,7 @@ message Alias {
}
]; // @gotags: `class:"public"`
// destination_id is the id of the resource that this Alias points to.
// destination_id is the id of the resource that this alias points to.
google.protobuf.StringValue destination_id = 100 [
json_name = "destination_id",
(custom_options.v1.generate_sdk_option) = true,
@@ -77,10 +86,23 @@ message Alias {
string type = 110; // @gotags: `class:"public" eventstream:"observation"`
oneof attrs {
// The attributes that are applicable for the specific Alias type.
// The attributes that are applicable for the specific alias type.
google.protobuf.Struct attributes = 120 [
(custom_options.v1.generate_sdk_option) = true,
(custom_options.v1.subtype) = "default"
(custom_options.v1.subtype) = "default",
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "{\"authorize_session_arguments\": {\"host_id\": \"host_id\"}}",
description:
"The attributes that are applicable for the specific alias type. "
"The schema of this field depends on the type of resource "
"that you create the alias for.\n"
"For target aliases, the parameters are:\n"
"```json\n"
"{\n"
" \"authorize_session_arguments\": {\"host_id\":\"host_id\"}\n"
"}\n"
"```\n"
}
];
TargetAliasAttributes target_alias_attributes = 121 [
(google.api.field_visibility).restriction = "INTERNAL",
@@ -89,12 +111,16 @@ message Alias {
];
}
// Output only. The available actions on this resource for this user.
repeated string authorized_actions = 300 [json_name = "authorized_actions"]; // @gotags: `class:"public"`
// The available actions on this resource for this user.
repeated string authorized_actions = 300 [
json_name = "authorized_actions",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public"`
}
// Attributes associated only with Aliases with type "target".
// Attributes associated only with aliases with type "target".
message TargetAliasAttributes {
// The arguments to provide to authorize_session of the target.
AuthorizeSessionArguments authorize_session_arguments = 1 [json_name = "authorize_session_arguments"]; // @gotags: `class:"public"`
}
internal/proto/controller/api/resources/scopes/v1/scope.proto
+45 -26
View File
@@ -6,6 +6,7 @@ syntax = "proto3";
package controller.api.resources.scopes.v1;
import "controller/custom_options/v1/options.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
@@ -13,32 +14,35 @@ import "google/protobuf/wrappers.proto";
option go_package = "github.com/hashicorp/boundary/sdk/pbs/controller/api/resources/scopes;scopes";
message ScopeInfo {
// Output only. The ID of the Scope.
string id = 1; // @gotags: `class:"public" eventstream:"observation"`
// The ID of the scope.
string id = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public" eventstream:"observation"`
// Output only. The type of the Scope.
string type = 2; // @gotags: `class:"public" eventstream:"observation"`
// The type of the scope.
string type = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public" eventstream:"observation"`
// Output only. The name of the Scope, if any.
string name = 3; // @gotags: `class:"public"`
// The name of the scope, if any.
string name = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public"`
// Output only. The description of the Scope, if any.
string description = 4; // @gotags: `class:"public"`
// The description of the scope, if any.
string description = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public"`
// Output only. The ID of the parent Scope, if any. This field will be empty if this is the "global" scope.
string parent_scope_id = 5 [json_name = "parent_scope_id"]; // @gotags: `class:"public" eventstream:"observation"`
// The ID of the parent scope, if any. This field is empty if it is the "global" scope.
string parent_scope_id = 5 [
json_name = "parent_scope_id",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public" eventstream:"observation"`
}
// Scope contains all fields related to a Scope resource
// Scope contains all fields related to a scope resource
message Scope {
// Output only. The ID of the Scope.
string id = 10; // @gotags: `class:"public" eventstream:"observation"`
// The ID of the scope.
string id = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; // @gotags: `class:"public" eventstream:"observation"`
// The ID of the Scope this resource is in. If this is the "global" Scope this field will be empty.
// The ID of the scope this resource is in. If this is the "global" scope this field will be empty.
string scope_id = 20 [json_name = "scope_id"]; // @gotags: `class:"public" eventstream:"observation"`
// Output only. Scope information for this resource.
ScopeInfo scope = 30;
// Scope information for this resource.
ScopeInfo scope = 30 [(google.api.field_behavior) = OUTPUT_ONLY];
// Optional name for identification purposes.
google.protobuf.StringValue name = 40 [
@@ -58,11 +62,17 @@ message Scope {
}
]; // @gotags: `class:"public"`
// Output only. The time this resource was created.
google.protobuf.Timestamp created_time = 60 [json_name = "created_time"]; // @gotags: `class:"public" eventstream:"observation"`
// The time this resource was created.
google.protobuf.Timestamp created_time = 60 [
json_name = "created_time",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public" eventstream:"observation"`
// Output only. The time this resource was last updated.
google.protobuf.Timestamp updated_time = 70 [json_name = "updated_time"]; // @gotags: `class:"public" eventstream:"observation"`
// The time this resource was last updated.
google.protobuf.Timestamp updated_time = 70 [
json_name = "updated_time",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public" eventstream:"observation"`
// Version is used in mutation requests, after the initial creation, to ensure this resource has not changed.
// The mutation will fail if the version does not match the latest known good version.
@@ -82,14 +92,23 @@ message Scope {
}
]; // @gotags: `class:"public" eventstream:"observation"`
// Output only. The available actions on this resource for this user.
repeated string authorized_actions = 300 [json_name = "authorized_actions"]; // @gotags: `class:"public"`
// The available actions on this resource for this user.
repeated string authorized_actions = 300 [
json_name = "authorized_actions",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public"`
// Output only. The authorized actions for the scope's collections.
map<string, google.protobuf.ListValue> authorized_collection_actions = 310 [json_name = "authorized_collection_actions"];
// The authorized actions for the scope's collections.
map<string, google.protobuf.ListValue> authorized_collection_actions = 310 [
json_name = "authorized_collection_actions",
(google.api.field_behavior) = OUTPUT_ONLY
];
// Output only. The attached storage policy id.
string storage_policy_id = 320 [json_name = "storage_policy_id"]; // @gotags: `class:"public"`
// The attached storage policy id.
string storage_policy_id = 320 [
json_name = "storage_policy_id",
(google.api.field_behavior) = OUTPUT_ONLY
]; // @gotags: `class:"public"`
}
// KeyVersion describes a specific version of a key and holds the actual key material