diff --git a/com/coralogix/openapi/v1/annotations.proto b/com/coralogix/openapi/v1/annotations.proto new file mode 100644 index 0000000..1081310 --- /dev/null +++ b/com/coralogix/openapi/v1/annotations.proto @@ -0,0 +1,158 @@ +syntax = "proto3"; + +package com.coralogix.openapi.v1; + +import "google/protobuf/descriptor.proto"; +import "google/protobuf/wrappers.proto"; + +// ServiceOpenAPI is a message used to annotate gRPC services with additional +// OpenAPI-specific metadata. This includes service description, version, and +// and error model full qualified name. +message ServiceOpenAPI { + string description = 1; // Description of the service. (deprecated) + string version = 2; // Version of the service. + string error_model = 3; // Full qualified name of error model used by the service (defaults to com.coralogix.openapi.ApiError). + string resource_name = 4; // Name of the resource used in openapi spec. (deprecated) + string name = 5; // Name of the service used in openapi spec. +} + +// Extending google.protobuf.ServiceOptions to include ServiceOpenAPI annotations. +// This allows attaching the ServiceOpenAPI metadata to gRPC service definitions. +extend google.protobuf.ServiceOptions { + ServiceOpenAPI service = 99999; +} + +// MethodOpenAPI is a message used to annotate gRPC methods with additional +// OpenAPI-specific metadata. This includes whether the method operates on a REST resource, +// its description, request schema, error responses, and the index of the HTTP rule where endpoints is defined. +message MethodOpenAPI { + bool resource = 1; // Indicates if the method operates on a REST resource. + string description = 3; // Description of the method. (Deprecated) + string request_schema = 4; // Schema of the request message. (Used when you want to use different schema than the one that will be generated from method request mesage type). + string response_schema = 5; // Schema of the response message. (Used when you want to use different schema than the one that will be generated from method response mesage type). + map error_responses = 6; // Map of error response codes to descriptions. + uint32 http_rule_index = 7; // Index of the associated HTTP rule. + string path_parameter_name = 8; // Name of the path parameter used in openapi spec. + map extensions = 9; // Map of extensions. Value is a free-form property to include a JSON of this field. This is copied to generated schema. Quotes must be escaped. + bool datasource = 10; // Indicates if the method is a datasource. + string request_body_example = 11; // A free-form property to include a JSON example of the request body. This is copied to generated schema. Quotes must be escaped. + string response_body_example = 12; // A free-form property to include a JSON example of the response body. This is copied to generated schema. Quotes must be escaped. + string name = 13; // Name of the method used in openapi spec. +} + +// Extending google.protobuf.MethodOptions to include MethodOpenAPI annotations. +// This allows attaching the MethodOpenAPI metadata to gRPC method definitions. +extend google.protobuf.MethodOptions { + MethodOpenAPI method = 99999; +} + +// MessageOpenAPI is a message used to annotate gRPC message types with additional +// OpenAPI-specific metadata, such as description and whether the message is a REST resource. +message MessageOpenAPI { + string name = 1; // Name of the message. + string description = 2; // Description of the message. + bool resource = 3; // Indicates if the message is a REST resource. + map extensions = 4; // Map of extensions. Value is a free-form property to include a JSON of this field. This is copied to generated schema. Quotes must be escaped. +} + +// Extending google.protobuf.MessageOptions to include MessageOpenAPI annotations. +// This allows attaching the MessageOpenAPI metadata to gRPC message definitions. +extend google.protobuf.MessageOptions { + MessageOpenAPI message = 99999; +} + +// EnumOpenAPI is a message used to annotate gRPC enum types with additional OpenAPI-specific metadata. +message EnumOpenAPI { + string name = 1; // Name of the enum. + string description = 2; // Description of the enum. + map extensions = 3; // Map of extensions. Value is a free-form property to include a JSON of this field. This is copied to generated schema. Quotes must be escaped. + +} + +// Extending google.protobuf.EnumOptions to include EnumOpenAPI annotations. +// This allows attaching the EnumOpenAPI metadata to gRPC enum definitions. +extend google.protobuf.EnumOptions { + EnumOpenAPI enum = 99999; +} + +// EnumValueOpenAPI is a message used to annotate enum values with additional OpenAPI-specific metadata. +message EnumValueOpenAPI { + repeated Cloud skip_in = 1; // List of clouds to skip this enum value in. +} + +// Extending google.protobuf.EnumValueOptions to include EnumValueOpenAPI annotations. +// This allows attaching the EnumValueOpenAPI metadata to enum value definitions. +extend google.protobuf.EnumValueOptions { + EnumValueOpenAPI enum_value = 99999; +} + +// FieldOpenAPI is a message used to annotate fields within gRPC message types +// with additional OpenAPI-specific metadata. This includes field descriptions, +// examples, validation patterns, length constraints, and other properties. +message FieldOpenAPI { + string name = 1; // Used for renaming field in OpenAPI schema. + string description = 2; // Description of the field. Defaults to the field name. + string example = 3; // A free-form property to include a JSON example of this field. This is copied to generated schema. Quotes must be escaped. + string pattern = 4; // Regex pattern the field value should match. + int32 min_length = 5; // Minimum length for string fields. Defaults to 1. + int32 max_length = 6; // Maximum length for string fields. Defaults to 4096. + int32 min_items = 7; // Minimum number of items for repeated fields. Defaults to 1. + int32 max_items = 8; // Maximum number of items for repeated fields. Defaults to 4096. + bool required = 9; // Indicates if the field is required. + bool identifier = 10; // Indicates if the field is an identifier. + string format = 11; // Format of the field. + repeated Cloud skip_in = 12; // List of clouds to skip this field in. +} + +// Extending google.protobuf.FieldOptions to include FieldOpenAPI annotations. +// This allows attaching the FieldOpenAPI metadata to field definitions within gRPC messages. +extend google.protobuf.FieldOptions { + FieldOpenAPI field = 99999; +} + +enum Cloud { + CLOUD_UNSPECIFIED = 0; + CLOUD_IBM = 1; + CLOUD_AWS = 2; + CLOUD_AZURE = 3; + CLOUD_GCP = 4; +} + +// ApiError is a message representing a standardized error response format. +// It contains a list of individual errors, a trace identifier, and a status code. +message ApiError { + // Nested message Error representing a single error occurrence. + message Error { + // Enum ErorCode defining possible error codes. + enum ErrorCode { + ERROR_CODE_BAD_REQUEST_OR_UNSPECIFIED = 0; + ERROR_CODE_UNAUTHORIZED = 1; + ERROR_CODE_FORBIDDEN = 2; + ERROR_CODE_NOT_FOUND = 3; + ERROR_CODE_METHOD_INTERNAL_ERROR = 4; + ERROR_CODE_CONFLICT = 5; + ERROR_CODE_UNAUTHENTICATED = 6; + ERROR_CODE_RESOURCE_EXHAUSTED = 7; + ERROR_CODE_DEADLINE_EXCEEDED = 8; + } + // Error code + ErrorCode code = 1 [(com.coralogix.openapi.v1.field) = { required: true } ]; + // Human-readable error message + google.protobuf.StringValue message = 2 [(com.coralogix.openapi.v1.field) = { example: "\"Not found\""} ]; + // Additional information about the error + google.protobuf.StringValue more_info = 3 [(com.coralogix.openapi.v1.field) = { example: "\"View not found\""} ]; + } + // List of errors + repeated Error errors = 1 [(com.coralogix.openapi.v1.field) = { required: true, min_length: 1 } ]; + // UUID uniquely identifying the request + google.protobuf.StringValue trace = 2 [(com.coralogix.openapi.v1.field) = { + required: true, + format : "uuid", + min_length : 36, + max_length : 36, + pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", + example: "\"3dc02998-0b50-4ea8-b68a-4779d716fa1f\"", + }]; + // HTTP status code associated with the error + google.protobuf.Int32Value status_code = 3 [(com.coralogix.openapi.v1.field) = { example: "404"}]; +} \ No newline at end of file diff --git a/com/coralogixapis/alerts/v3/alert_def.proto b/com/coralogixapis/alerts/v3/alert_def.proto index 7043dff..bdc3945 100644 --- a/com/coralogixapis/alerts/v3/alert_def.proto +++ b/com/coralogixapis/alerts/v3/alert_def.proto @@ -20,22 +20,39 @@ import "com/coralogixapis/alerts/v3/alert_def_type_definition/tracing/tracing_th import "com/coralogixapis/alerts/v3/alert_def_type_definition/logs/logs_unique_count_type_definition.proto"; import "google/protobuf/timestamp.proto"; import "google/protobuf/wrappers.proto"; +import "com/coralogix/openapi/v1/annotations.proto"; /** * Represents An Existing or Created Alert Definition */ message AlertDef { - AlertDefProperties alert_def_properties = 1; - google.protobuf.StringValue id = 2; // This is the Alert Definition's Persistent ID (does not change on replace) , AKA UniqueIdentifier - google.protobuf.StringValue alert_version_id = 20; // the old alertId - google.protobuf.Timestamp created_time = 3; - google.protobuf.Timestamp updated_time = 4; + option (com.coralogix.openapi.v1.message) = { + resource: true + }; + AlertDefProperties alert_def_properties = 1 [(com.coralogix.openapi.v1.field) = { + required: true + }]; + // This is the Alert Definition's Persistent ID (does not change on replace) , AKA UniqueIdentifier + google.protobuf.StringValue id = 2 [(com.coralogix.openapi.v1.field) = { + required: true + }]; + // the old alertId + google.protobuf.StringValue alert_version_id = 20; + google.protobuf.Timestamp created_time = 3 [(com.coralogix.openapi.v1.field) = { + required: true + }]; + google.protobuf.Timestamp updated_time = 4 [(com.coralogix.openapi.v1.field) = { + required: true + }]; } /** * Represents The non generated alert definition properties (the ones that are set by the user) */ message AlertDefProperties { + option (com.coralogix.openapi.v1.message) = { + name: "AlertDefPrototype" + }; google.protobuf.StringValue name = 1; google.protobuf.StringValue description = 2; google.protobuf.BoolValue enabled = 3; diff --git a/com/coralogixapis/alerts/v3/alert_defs_service.proto b/com/coralogixapis/alerts/v3/alert_defs_service.proto index 44cf01a..70d5b54 100644 --- a/com/coralogixapis/alerts/v3/alert_defs_service.proto +++ b/com/coralogixapis/alerts/v3/alert_defs_service.proto @@ -8,6 +8,7 @@ import "google/protobuf/wrappers.proto"; import "google/protobuf/timestamp.proto"; import "com/coralogixapis/alerts/v3/alert_def.proto"; import "com/coralogixapis/alerts/v3/alert_def_type.proto"; +import "com/coralogix/openapi/v1/annotations.proto"; message AuditLogDescription { optional string description = 1; @@ -17,28 +18,48 @@ extend google.protobuf.MethodOptions { optional AuditLogDescription audit_log_description = 5000; } +// API to manage alert definitions service AlertDefsService { - // Get Alert Def by non changing ID AKA UniqueIdentifier + option (com.coralogix.openapi.v1.service) = { + name: "Alert Definitions" + resource_name: "AlertDef" + }; + // Get Alert Definition by non changing ID AKA UniqueIdentifier rpc GetAlertDef(GetAlertDefRequest) returns (GetAlertDefResponse) { option (audit_log_description).description = "get alert definition"; option (google.api.http) = { - get: "/v3/alert-defs/{id}" + get: "/v1/alert_defs/{id}" + response_body: "alert_def" }; + option (com.coralogix.openapi.v1.method) = { + resource: true + }; + } + // Create Alert Definition rpc CreateAlertDef(CreateAlertDefRequest) returns (CreateAlertDefResponse){ option (audit_log_description).description = "create alert definition"; option (google.api.http) = { - post: "/v3/alert-defs" - body: "alertDef" + post: "/v1/alert_defs" + body: "alert_def_properties" + response_body: "alert_def" + }; + option (com.coralogix.openapi.v1.method) = { + resource: true }; } + // Replace Alert Definition by ID AKA UniqueIdentifier rpc ReplaceAlertDef(ReplaceAlertDefRequest) returns (ReplaceAlertDefResponse){ option (audit_log_description).description = "replace alert definition"; option (google.api.http) = { - put: "/v3/alert-defs" - body: "alertDef" + put: "/v1/alert_defs/{id}" + body: "alert_def_properties" + response_body: "alert_def" + }; + option (com.coralogix.openapi.v1.method) = { + resource: true }; } @@ -48,19 +69,26 @@ service AlertDefsService { // get: "/v3/alertDefs:batchGet" // }; // } - + + // List all Alert Defitions rpc ListAlertDefs(ListAlertDefsRequest) returns (ListAlertDefsResponse){ option (audit_log_description).description = "get alert definitions list"; option (google.api.http) = { - get: "/v3/alert-defs" - body: "*" + get: "/v1/alert_defs" + }; + option (com.coralogix.openapi.v1.method) = { + resource: true }; } + // Delete Alert Definition by ID AKA UniqueIdentifier rpc DeleteAlertDef(DeleteAlertDefRequest) returns (DeleteAlertDefResponse){ option (audit_log_description).description = "delete alert definitions"; option (google.api.http) = { - delete: "/v3/alert-defs/{id}" + delete: "/v1/alert_defs/{id}" + }; + option (com.coralogix.openapi.v1.method) = { + resource: true }; } @@ -88,10 +116,11 @@ service AlertDefsService { // }; // } + // Set Active status of an alert definition rpc SetActive(SetActiveRequest) returns (SetActiveResponse) { option (audit_log_description).description = "disable or enable the alert definitions"; option (google.api.http) = { - post: "/v3/alert-defs/{id}:SetActive" + post: "/v2/alerts/{id}:SetActive" }; } } @@ -123,7 +152,10 @@ message GetAlertDefResponse { } message ListAlertDefsResponse { - repeated AlertDef alert_defs = 1; + option (com.coralogix.openapi.v1.message) = { + name: "AlertDefCollection" + }; + repeated AlertDef alert_defs = 1 [ (com.coralogix.openapi.v1.field) = { required: true } ]; } message ListAlertDefsRequest {