Pg 2523 ibm openapi facade annotations

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<uint32, string> 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<string, string> 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<string, string> 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<string, string> 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"}];
+}

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;

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 {