internal/proto: improvements to OpenAPIv2 spec (#4555)
* 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:
69 files changed
+4339
-1803
No files matched your search
@@ -128,15 +128,18 @@ type ListHostSetsRequest struct {
|
||||
unknownFields protoimpl.UnknownFields
|
||||
|
||||
HostCatalogId string `protobuf:"bytes,1,opt,name=host_catalog_id,proto3" json:"host_catalog_id,omitempty" class:"public"` // @gotags: `class:"public"`
|
||||
Filter string `protobuf:"bytes,30,opt,name=filter,proto3" json:"filter,omitempty" class:"public"` // @gotags: `class:"public"`
|
||||
// An opaque token used to continue an existing iteration or
|
||||
// request updated items. If not specified, pagination
|
||||
// will start from the beginning.
|
||||
// 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:"public"` // @gotags: `class:"public"`
|
||||
// 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.
|
||||
// the page size will be truncated to this number..
|
||||
PageSize uint32 `protobuf:"varint,50,opt,name=page_size,proto3" json:"page_size,omitempty" class:"public"` // @gotags: `class:"public"`
|
||||
}
|
||||
|
||||
@@ -1070,7 +1073,7 @@ var file_controller_api_services_v1_host_set_service_proto_rawDesc = []byte{
|
||||
0x01, 0x20, 0x01, 0x28, 0x0b, 0x32, 0x2d, 0x2e, 0x63, 0x6f, 0x6e, 0x74, 0x72, 0x6f, 0x6c, 0x6c,
|
||||
0x65, 0x72, 0x2e, 0x61, 0x70, 0x69, 0x2e, 0x72, 0x65, 0x73, 0x6f, 0x75, 0x72, 0x63, 0x65, 0x73,
|
||||
0x2e, 0x68, 0x6f, 0x73, 0x74, 0x73, 0x65, 0x74, 0x73, 0x2e, 0x76, 0x31, 0x2e, 0x48, 0x6f, 0x73,
|
||||
0x74, 0x53, 0x65, 0x74, 0x52, 0x04, 0x69, 0x74, 0x65, 0x6d, 0x32, 0x8a, 0x0c, 0x0a, 0x0e, 0x48,
|
||||
0x74, 0x53, 0x65, 0x74, 0x52, 0x04, 0x69, 0x74, 0x65, 0x6d, 0x32, 0xf8, 0x0e, 0x0a, 0x0e, 0x48,
|
||||
0x6f, 0x73, 0x74, 0x53, 0x65, 0x74, 0x53, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x12, 0xa8, 0x01,
|
||||
0x0a, 0x0a, 0x47, 0x65, 0x74, 0x48, 0x6f, 0x73, 0x74, 0x53, 0x65, 0x74, 0x12, 0x2d, 0x2e, 0x63,
|
||||
0x6f, 0x6e, 0x74, 0x72, 0x6f, 0x6c, 0x6c, 0x65, 0x72, 0x2e, 0x61, 0x70, 0x69, 0x2e, 0x73, 0x65,
|
||||
@@ -1167,13 +1170,36 @@ var file_controller_api_services_v1_host_set_service_proto_rawDesc = []byte{
|
||||
0x73, 0x74, 0x20, 0x53, 0x65, 0x74, 0x2e, 0x82, 0xd3, 0xe4, 0x93, 0x02, 0x2a, 0x3a, 0x01, 0x2a,
|
||||
0x62, 0x04, 0x69, 0x74, 0x65, 0x6d, 0x22, 0x1f, 0x2f, 0x76, 0x31, 0x2f, 0x68, 0x6f, 0x73, 0x74,
|
||||
0x2d, 0x73, 0x65, 0x74, 0x73, 0x2f, 0x7b, 0x69, 0x64, 0x7d, 0x3a, 0x72, 0x65, 0x6d, 0x6f, 0x76,
|
||||
0x65, 0x2d, 0x68, 0x6f, 0x73, 0x74, 0x73, 0x42, 0x55, 0xa2, 0xe3, 0x29, 0x04, 0x68, 0x6f, 0x73,
|
||||
0x74, 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,
|
||||
0x65, 0x2d, 0x68, 0x6f, 0x73, 0x74, 0x73, 0x1a, 0xeb, 0x02, 0x92, 0x41, 0xe7, 0x02, 0x0a, 0x10,
|
||||
0x48, 0x6f, 0x73, 0x74, 0x20, 0x73, 0x65, 0x74, 0x20, 0x73, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65,
|
||||
0x12, 0xcd, 0x01, 0x41, 0x20, 0x68, 0x6f, 0x73, 0x74, 0x20, 0x73, 0x65, 0x74, 0x20, 0x69, 0x73,
|
||||
0x20, 0x61, 0x20, 0x72, 0x65, 0x73, 0x6f, 0x75, 0x72, 0x63, 0x65, 0x20, 0x74, 0x68, 0x61, 0x74,
|
||||
0x20, 0x72, 0x65, 0x70, 0x72, 0x65, 0x73, 0x65, 0x6e, 0x74, 0x73, 0x20, 0x61, 0x20, 0x63, 0x6f,
|
||||
0x6c, 0x6c, 0x65, 0x63, 0x74, 0x69, 0x6f, 0x6e, 0x20, 0x6f, 0x66, 0x20, 0x68, 0x6f, 0x73, 0x74,
|
||||
0x73, 0x20, 0x74, 0x68, 0x61, 0x74, 0x20, 0x61, 0x72, 0x65, 0x20, 0x63, 0x6f, 0x6e, 0x73, 0x69,
|
||||
0x64, 0x65, 0x72, 0x65, 0x64, 0x20, 0x65, 0x71, 0x75, 0x69, 0x76, 0x61, 0x6c, 0x65, 0x6e, 0x74,
|
||||
0x20, 0x66, 0x6f, 0x72, 0x20, 0x74, 0x68, 0x65, 0x20, 0x70, 0x75, 0x72, 0x70, 0x6f, 0x73, 0x65,
|
||||
0x73, 0x20, 0x6f, 0x66, 0x20, 0x61, 0x63, 0x63, 0x65, 0x73, 0x73, 0x20, 0x63, 0x6f, 0x6e, 0x74,
|
||||
0x72, 0x6f, 0x6c, 0x2e, 0x20, 0x54, 0x68, 0x65, 0x20, 0x68, 0x6f, 0x73, 0x74, 0x20, 0x73, 0x65,
|
||||
0x74, 0x20, 0x73, 0x65, 0x72, 0x76, 0x69, 0x63, 0x65, 0x20, 0x70, 0x72, 0x6f, 0x76, 0x69, 0x64,
|
||||
0x65, 0x73, 0x20, 0x65, 0x6e, 0x64, 0x70, 0x6f, 0x69, 0x6e, 0x74, 0x73, 0x20, 0x66, 0x6f, 0x72,
|
||||
0x20, 0x6d, 0x61, 0x6e, 0x61, 0x67, 0x69, 0x6e, 0x67, 0x20, 0x68, 0x6f, 0x73, 0x74, 0x20, 0x73,
|
||||
0x65, 0x74, 0x73, 0x20, 0x69, 0x6e, 0x20, 0x42, 0x6f, 0x75, 0x6e, 0x64, 0x61, 0x72, 0x79, 0x2e,
|
||||
0x1a, 0x82, 0x01, 0x0a, 0x31, 0x52, 0x65, 0x61, 0x64, 0x20, 0x61, 0x62, 0x6f, 0x75, 0x74, 0x20,
|
||||
0x68, 0x6f, 0x73, 0x74, 0x20, 0x73, 0x65, 0x74, 0x73, 0x20, 0x69, 0x6e, 0x20, 0x74, 0x68, 0x65,
|
||||
0x20, 0x42, 0x6f, 0x75, 0x6e, 0x64, 0x61, 0x72, 0x79, 0x20, 0x64, 0x6f, 0x6d, 0x61, 0x69, 0x6e,
|
||||
0x20, 0x6d, 0x6f, 0x64, 0x65, 0x6c, 0x12, 0x4d, 0x68, 0x74, 0x74, 0x70, 0x73, 0x3a, 0x2f, 0x2f,
|
||||
0x64, 0x65, 0x76, 0x65, 0x6c, 0x6f, 0x70, 0x65, 0x72, 0x2e, 0x68, 0x61, 0x73, 0x68, 0x69, 0x63,
|
||||
0x6f, 0x72, 0x70, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x62, 0x6f, 0x75, 0x6e, 0x64, 0x61, 0x72, 0x79,
|
||||
0x2f, 0x64, 0x6f, 0x63, 0x73, 0x2f, 0x63, 0x6f, 0x6e, 0x63, 0x65, 0x70, 0x74, 0x73, 0x2f, 0x64,
|
||||
0x6f, 0x6d, 0x61, 0x69, 0x6e, 0x2d, 0x6d, 0x6f, 0x64, 0x65, 0x6c, 0x2f, 0x68, 0x6f, 0x73, 0x74,
|
||||
0x2d, 0x73, 0x65, 0x74, 0x73, 0x42, 0x55, 0xa2, 0xe3, 0x29, 0x04, 0x68, 0x6f, 0x73, 0x74, 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 (
|
||||
|
||||
Reference in new issue
Block a user