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/gen/controller/api/services/alias_service.pb.go
+49 -18
View File
@@ -33,6 +33,7 @@ type GetAliasRequest struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
// The ID of the alias to retrieve.
Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty" class:"public" eventstream:"observation"` // @gotags: `class:"public" eventstream:"observation"`
}
@@ -127,17 +128,22 @@ type ListAliasesRequest struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
ScopeId string `protobuf:"bytes,1,opt,name=scope_id,proto3" json:"scope_id,omitempty" class:"public" eventstream:"observation"` // @gotags: `class:"public" eventstream:"observation"`
Recursive bool `protobuf:"varint,2,opt,name=recursive,proto3" json:"recursive,omitempty" class:"public"` // @gotags: `class:"public"`
Filter string `protobuf:"bytes,30,opt,name=filter,proto3" json:"filter,omitempty" class:"sensitive"` // @gotags: `class:"sensitive"`
// An opaque token used to continue an existing iteration or
// request updated items. If not specified, pagination
// will start from the beginning.
// The ID of the scope in which to list aliases
ScopeId string `protobuf:"bytes,1,opt,name=scope_id,proto3" json:"scope_id,omitempty" class:"public" eventstream:"observation"` // @gotags: `class:"public" eventstream:"observation"`
// Whether to recursively list aliases in the provided scope's child scopes.
Recursive bool `protobuf:"varint,2,opt,name=recursive,proto3" json:"recursive,omitempty" class:"public"` // @gotags: `class:"public"`
// You can specify that the filter should only return items that match.
// Refer to [filter expressions](https://developer.hashicorp.com/boundary/docs/concepts/filtering) for more information.
Filter string `protobuf:"bytes,30,opt,name=filter,proto3" json:"filter,omitempty" class:"sensitive"` // @gotags: `class:"sensitive"`
// An opaque token that Boundary uses to continue an existing iteration or
// request updated items. If you do not specify a token, pagination
// starts from the beginning. To learn more about list pagination
// in Boundary, refer to [list pagination](https://developer.hashicorp.com/boundary/docs/api-clients/api/pagination).
ListToken string `protobuf:"bytes,40,opt,name=list_token,proto3" json:"list_token,omitempty" class:"public"` // @gotags: `class:"public"`
// The maximum size of a page in this iteration.
// If unset, the default page size configured will be used.
// If the page_size is greater than the default page configured,
// an error will be returned.
// If you do not set a page size, Boundary uses the configured default page size.
// If the page_size is greater than the default page size configured,
// Boundary truncates the page size to this number.
PageSize uint32 `protobuf:"varint,50,opt,name=page_size,proto3" json:"page_size,omitempty" class:"public"` // @gotags: `class:"public"`
}
@@ -213,6 +219,7 @@ type ListAliasesResponse struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
// The list of aliases.
Items []*aliases.Alias `protobuf:"bytes,1,rep,name=items,proto3" json:"items,omitempty"`
// The type of response, either "delta" or "complete".
// Delta signifies that this is part of a paginated result
@@ -424,7 +431,9 @@ type UpdateAliasRequest struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty" class:"public" eventstream:"observation"` // @gotags: `class:"public" eventstream:"observation"`
// The ID of the alias to update.
Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty" class:"public" eventstream:"observation"` // @gotags: `class:"public" eventstream:"observation"`
// A subset of the alias that contains the fields to update.
Item *aliases.Alias `protobuf:"bytes,2,opt,name=item,proto3" json:"item,omitempty"`
UpdateMask *fieldmaskpb.FieldMask `protobuf:"bytes,3,opt,name=update_mask,proto3" json:"update_mask,omitempty"`
}
@@ -534,6 +543,7 @@ type DeleteAliasRequest struct {
sizeCache protoimpl.SizeCache
unknownFields protoimpl.UnknownFields
// The ID of the alias to delete.
Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty" class:"public" eventstream:"observation"` // @gotags: `class:"public" eventstream:"observation"`
}
@@ -702,7 +712,7 @@ var file_controller_api_services_v1_alias_service_proto_rawDesc = []byte{
0x73, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x12, 0x0e, 0x0a, 0x02, 0x69, 0x64, 0x18, 0x01,
0x20, 0x01, 0x28, 0x09, 0x52, 0x02, 0x69, 0x64, 0x22, 0x15, 0x0a, 0x13, 0x44, 0x65, 0x6c, 0x65,
0x74, 0x65, 0x41, 0x6c, 0x69, 0x61, 0x73, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x32,
0xf2, 0x06, 0x0a, 0x0c, 0x41, 0x6c, 0x69, 0x61, 0x73, 0x53, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65,
0xc1, 0x09, 0x0a, 0x0c, 0x41, 0x6c, 0x69, 0x61, 0x73, 0x53, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65,
0x12, 0x9e, 0x01, 0x0a, 0x08, 0x47, 0x65, 0x74, 0x41, 0x6c, 0x69, 0x61, 0x73, 0x12, 0x2b, 0x2e,
0x63, 0x6f, 0x6e, 0x74, 0x72, 0x6f, 0x6c, 0x6c, 0x65, 0x72, 0x2e, 0x61, 0x70, 0x69, 0x2e, 0x73,
0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x73, 0x2e, 0x76, 0x31, 0x2e, 0x47, 0x65, 0x74, 0x41, 0x6c,
@@ -757,13 +767,34 @@ var file_controller_api_services_v1_alias_service_proto_rawDesc = []byte{
0x6f, 0x6e, 0x73, 0x65, 0x22, 0x2e, 0x92, 0x41, 0x13, 0x12, 0x11, 0x44, 0x65, 0x6c, 0x65, 0x74,
0x65, 0x73, 0x20, 0x61, 0x6e, 0x20, 0x41, 0x6c, 0x69, 0x61, 0x73, 0x2e, 0x82, 0xd3, 0xe4, 0x93,
0x02, 0x12, 0x2a, 0x10, 0x2f, 0x76, 0x31, 0x2f, 0x61, 0x6c, 0x69, 0x61, 0x73, 0x65, 0x73, 0x2f,
0x7b, 0x69, 0x64, 0x7d, 0x42, 0x55, 0xa2, 0xe3, 0x29, 0x04, 0x61, 0x75, 0x74, 0x68, 0x5a, 0x4b,
0x67, 0x69, 0x74, 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x68, 0x61, 0x73, 0x68, 0x69,
0x63, 0x6f, 0x72, 0x70, 0x2f, 0x62, 0x6f, 0x75, 0x6e, 0x64, 0x61, 0x72, 0x79, 0x2f, 0x69, 0x6e,
0x74, 0x65, 0x72, 0x6e, 0x61, 0x6c, 0x2f, 0x67, 0x65, 0x6e, 0x2f, 0x63, 0x6f, 0x6e, 0x74, 0x72,
0x6f, 0x6c, 0x6c, 0x65, 0x72, 0x2f, 0x61, 0x70, 0x69, 0x2f, 0x73, 0x65, 0x72, 0x76, 0x69, 0x63,
0x65, 0x73, 0x3b, 0x73, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x73, 0x62, 0x06, 0x70, 0x72, 0x6f,
0x74, 0x6f, 0x33,
0x7b, 0x69, 0x64, 0x7d, 0x1a, 0xcc, 0x02, 0x92, 0x41, 0xc8, 0x02, 0x0a, 0x0d, 0x41, 0x6c, 0x69,
0x61, 0x73, 0x20, 0x73, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x12, 0xb6, 0x02, 0x54, 0x68, 0x65,
0x20, 0x61, 0x6c, 0x69, 0x61, 0x73, 0x20, 0x73, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x20, 0x65,
0x78, 0x70, 0x6f, 0x73, 0x65, 0x73, 0x20, 0x65, 0x6e, 0x64, 0x70, 0x6f, 0x69, 0x6e, 0x74, 0x73,
0x20, 0x66, 0x6f, 0x72, 0x20, 0x69, 0x6e, 0x74, 0x65, 0x72, 0x61, 0x63, 0x74, 0x69, 0x6e, 0x67,
0x20, 0x77, 0x69, 0x74, 0x68, 0x20, 0x61, 0x6c, 0x69, 0x61, 0x73, 0x65, 0x73, 0x20, 0x69, 0x6e,
0x20, 0x42, 0x6f, 0x75, 0x6e, 0x64, 0x61, 0x72, 0x79, 0x2e, 0x20, 0x41, 0x6e, 0x20, 0x61, 0x6c,
0x69, 0x61, 0x73, 0x20, 0x61, 0x63, 0x74, 0x73, 0x20, 0x61, 0x73, 0x20, 0x61, 0x20, 0x72, 0x65,
0x66, 0x65, 0x72, 0x65, 0x6e, 0x63, 0x65, 0x20, 0x6f, 0x72, 0x20, 0x61, 0x6e, 0x20, 0x61, 0x6c,
0x74, 0x65, 0x72, 0x6e, 0x61, 0x74, 0x65, 0x20, 0x49, 0x44, 0x20, 0x66, 0x6f, 0x72, 0x20, 0x61,
0x6e, 0x20, 0x65, 0x78, 0x69, 0x73, 0x74, 0x69, 0x6e, 0x67, 0x20, 0x65, 0x6e, 0x74, 0x69, 0x74,
0x79, 0x20, 0x77, 0x69, 0x74, 0x68, 0x69, 0x6e, 0x20, 0x74, 0x68, 0x65, 0x20, 0x42, 0x6f, 0x75,
0x6e, 0x64, 0x61, 0x72, 0x79, 0x20, 0x61, 0x63, 0x63, 0x65, 0x73, 0x73, 0x20, 0x63, 0x6f, 0x6e,
0x74, 0x72, 0x6f, 0x6c, 0x20, 0x73, 0x79, 0x73, 0x74, 0x65, 0x6d, 0x2e, 0x20, 0x49, 0x74, 0x20,
0x70, 0x72, 0x6f, 0x76, 0x69, 0x64, 0x65, 0x73, 0x20, 0x61, 0x20, 0x77, 0x61, 0x79, 0x20, 0x74,
0x6f, 0x20, 0x73, 0x69, 0x6d, 0x70, 0x6c, 0x69, 0x66, 0x79, 0x20, 0x61, 0x63, 0x63, 0x65, 0x73,
0x73, 0x20, 0x63, 0x6f, 0x6e, 0x74, 0x72, 0x6f, 0x6c, 0x20, 0x62, 0x79, 0x20, 0x6f, 0x66, 0x66,
0x65, 0x72, 0x69, 0x6e, 0x67, 0x20, 0x61, 0x20, 0x6d, 0x6f, 0x72, 0x65, 0x20, 0x75, 0x73, 0x65,
0x72, 0x2d, 0x66, 0x72, 0x69, 0x65, 0x6e, 0x64, 0x6c, 0x79, 0x20, 0x6f, 0x72, 0x20, 0x64, 0x65,
0x73, 0x63, 0x72, 0x69, 0x70, 0x74, 0x69, 0x76, 0x65, 0x20, 0x69, 0x64, 0x65, 0x6e, 0x74, 0x69,
0x66, 0x69, 0x65, 0x72, 0x20, 0x66, 0x6f, 0x72, 0x20, 0x61, 0x6e, 0x20, 0x65, 0x6e, 0x74, 0x69,
0x74, 0x79, 0x2e, 0x42, 0x55, 0xa2, 0xe3, 0x29, 0x04, 0x61, 0x75, 0x74, 0x68, 0x5a, 0x4b, 0x67,
0x69, 0x74, 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x68, 0x61, 0x73, 0x68, 0x69, 0x63,
0x6f, 0x72, 0x70, 0x2f, 0x62, 0x6f, 0x75, 0x6e, 0x64, 0x61, 0x72, 0x79, 0x2f, 0x69, 0x6e, 0x74,
0x65, 0x72, 0x6e, 0x61, 0x6c, 0x2f, 0x67, 0x65, 0x6e, 0x2f, 0x63, 0x6f, 0x6e, 0x74, 0x72, 0x6f,
0x6c, 0x6c, 0x65, 0x72, 0x2f, 0x61, 0x70, 0x69, 0x2f, 0x73, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65,
0x73, 0x3b, 0x73, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x73, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74,
0x6f, 0x33,
}
var (