[PLAT-18823] Annotate YBA HA APIs to document them

Summary: the current YBA HA APIs are undocumented,We need to document these APIs which are well tested and ready to be consumed

Test Plan: manual

Reviewers: #yba-api-review, dkumar

Reviewed By: #yba-api-review, dkumar

Subscribers: yugaware

Differential Revision: https://phorge.dev.yugabyte.com/D48139

Author: satvik279

managed/src/main/java/com/yugabyte/yw/controllers/HAController.java

@@ -23,12 +23,17 @@
 import com.yugabyte.yw.models.Audit;
 import com.yugabyte.yw.models.HighAvailabilityConfig;
 import com.yugabyte.yw.models.PlatformInstance;
+import com.yugabyte.yw.models.common.YbaApi;
 import com.yugabyte.yw.rbac.annotations.AuthzPath;
 import com.yugabyte.yw.rbac.annotations.PermissionAttribute;
 import com.yugabyte.yw.rbac.annotations.RequiredPermissionOnResource;
 import com.yugabyte.yw.rbac.annotations.Resource;
 import com.yugabyte.yw.rbac.enums.SourceType;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
 import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.Authorization;
 import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
@@ -39,10 +44,23 @@
 import play.mvc.Result;
 import play.mvc.Results;
 
+@Api(value = "HA", authorizations = @Authorization(AbstractPlatformController.API_KEY_AUTH))
 @Slf4j
 public class HAController extends AuthenticatedController {
   @Inject private PlatformReplicationManager replicationManager;
 
+  @ApiOperation(
+      notes = "Available since YBA version 2.20.0.",
+      nickname = "createHAConfig",
+      value = "Create high availability config",
+      response = HighAvailabilityConfig.class)
+  @ApiImplicitParams(
+      @ApiImplicitParam(
+          name = "HAConfigFormRequest",
+          paramType = "body",
+          dataType = "com.yugabyte.yw.forms.HAConfigFormData",
+          required = true))
+  @YbaApi(visibility = YbaApi.YbaApiVisibility.PUBLIC, sinceYBAVersion = "2.20.0")
   @AuthzPath({
     @RequiredPermissionOnResource(
         requiredPermission =
@@ -152,6 +170,12 @@ public Result deleteHAConfig(UUID configUUID, Http.Request request) {
     return ok();
   }
 
+  @ApiOperation(
+      notes = "Available since YBA version 2.20.0.",
+      value = "Generate cluster key",
+      response = JsonNode.class,
+      nickname = "generateClusterKey")
+  @YbaApi(visibility = YbaApi.YbaApiVisibility.PUBLIC, sinceYBAVersion = "2.20.0")
   @AuthzPath({
     @RequiredPermissionOnResource(
         requiredPermission =

managed/src/main/java/com/yugabyte/yw/controllers/InternalHAController.java

@@ -23,6 +23,9 @@
 import com.yugabyte.yw.forms.PlatformResults.YBPSuccess;
 import com.yugabyte.yw.models.HighAvailabilityConfig;
 import com.yugabyte.yw.models.PlatformInstance;
+import com.yugabyte.yw.models.common.YbaApi;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import java.net.URL;
 import java.util.Date;
 import java.util.List;
@@ -39,6 +42,7 @@
 import play.mvc.Result;
 import play.mvc.With;
 
+@Api(value = "Internal HA")
 @With(HAAuthenticator.class)
 @Slf4j
 public class InternalHAController extends Controller {
@@ -180,6 +184,12 @@ public Result syncBackups(Http.Request request) throws Exception {
   }
 
   /** This is invoked by the remote peer to demote this local leader. */
+  @ApiOperation(
+      notes = "Available since YBA version 2.20.0.",
+      value = "Demote local leader",
+      response = PlatformInstance.class,
+      nickname = "demoteLocalLeader")
+  @YbaApi(visibility = YbaApi.YbaApiVisibility.PUBLIC, sinceYBAVersion = "2.20.0")
   public Result demoteLocalLeader(long timestamp, boolean promote, Http.Request request) {
     log.debug("Received request to demote local instance from {}", request.remoteAddress());
     String clusterKey = getClusterKey(request);

managed/src/main/java/com/yugabyte/yw/controllers/PlatformInstanceController.java

@@ -25,11 +25,17 @@
 import com.yugabyte.yw.models.Audit;
 import com.yugabyte.yw.models.HighAvailabilityConfig;
 import com.yugabyte.yw.models.PlatformInstance;
+import com.yugabyte.yw.models.common.YbaApi;
 import com.yugabyte.yw.rbac.annotations.AuthzPath;
 import com.yugabyte.yw.rbac.annotations.PermissionAttribute;
 import com.yugabyte.yw.rbac.annotations.RequiredPermissionOnResource;
 import com.yugabyte.yw.rbac.annotations.Resource;
 import com.yugabyte.yw.rbac.enums.SourceType;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.Authorization;
 import java.io.File;
 import java.net.URL;
 import java.util.Objects;
@@ -40,6 +46,9 @@
 import play.mvc.Http;
 import play.mvc.Result;
 
+@Api(
+    value = "Platform Instance",
+    authorizations = @Authorization(AbstractPlatformController.API_KEY_AUTH))
 @Slf4j
 public class PlatformInstanceController extends AuthenticatedController {
   @Inject private PlatformReplicationManager replicationManager;
@@ -48,6 +57,18 @@ public class PlatformInstanceController extends AuthenticatedController {
 
   @Inject CustomerTaskManager taskManager;
 
+  @ApiOperation(
+      notes = "Available since YBA version 2.20.0.",
+      value = "Create platform instance",
+      response = PlatformInstance.class,
+      nickname = "createInstance")
+  @ApiImplicitParams(
+      @ApiImplicitParam(
+          name = "PlatformInstanceFormRequest",
+          paramType = "body",
+          dataType = "com.yugabyte.yw.forms.PlatformInstanceFormData",
+          required = true))
+  @YbaApi(visibility = YbaApi.YbaApiVisibility.PUBLIC, sinceYBAVersion = "2.20.0")
   @AuthzPath({
     @RequiredPermissionOnResource(
         requiredPermission =
@@ -185,6 +206,17 @@ public Result getLocal(UUID configUUID) {
     return PlatformResults.withData(localInstance.get());
   }
 
+  @ApiOperation(
+      notes = "Available since YBA version 2.20.0.",
+      value = "Promote platform instance",
+      nickname = "promoteInstance")
+  @ApiImplicitParams(
+      @ApiImplicitParam(
+          name = "PlatformBackupRestoreRequest",
+          paramType = "body",
+          dataType = "com.yugabyte.yw.forms.RestorePlatformBackupFormData",
+          required = true))
+  @YbaApi(visibility = YbaApi.YbaApiVisibility.PUBLIC, sinceYBAVersion = "2.20.0")
   @AuthzPath({
     @RequiredPermissionOnResource(
         requiredPermission =

managed/src/main/java/com/yugabyte/yw/controllers/PlatformReplicationController.java

@@ -23,11 +23,17 @@
 import com.yugabyte.yw.models.Audit;
 import com.yugabyte.yw.models.HighAvailabilityConfig;
 import com.yugabyte.yw.models.PlatformInstance;
+import com.yugabyte.yw.models.common.YbaApi;
 import com.yugabyte.yw.rbac.annotations.AuthzPath;
 import com.yugabyte.yw.rbac.annotations.PermissionAttribute;
 import com.yugabyte.yw.rbac.annotations.RequiredPermissionOnResource;
 import com.yugabyte.yw.rbac.annotations.Resource;
 import com.yugabyte.yw.rbac.enums.SourceType;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.Authorization;
 import java.io.File;
 import java.time.Duration;
 import java.util.Collections;
@@ -39,10 +45,25 @@
 import play.mvc.Http;
 import play.mvc.Result;
 
+@Api(
+    value = "Platform Replication",
+    authorizations = @Authorization(AbstractPlatformController.API_KEY_AUTH))
 public class PlatformReplicationController extends AuthenticatedController {
 
   @Inject private PlatformReplicationManager replicationManager;
 
+  @ApiOperation(
+      notes = "Available since YBA version 2.20.0.",
+      value = "Start periodic backup",
+      response = JsonNode.class,
+      nickname = "startPeriodicBackup")
+  @ApiImplicitParams(
+      @ApiImplicitParam(
+          name = "PlatformBackupFrequencyRequest",
+          paramType = "body",
+          dataType = "com.yugabyte.yw.forms.PlatformBackupFrequencyFormData",
+          required = true))
+  @YbaApi(visibility = YbaApi.YbaApiVisibility.PUBLIC, sinceYBAVersion = "2.20.0")
   @AuthzPath({
     @RequiredPermissionOnResource(
         requiredPermission =
@@ -104,6 +125,13 @@ public Result getBackupInfo(UUID configUUID) {
     return ok(replicationManager.getBackupInfo());
   }
 
+  @ApiOperation(
+      notes = "Available since YBA version 2.20.0.",
+      nickname = "listBackups",
+      value = "List backups",
+      response = String.class,
+      responseContainer = "List")
+  @YbaApi(visibility = YbaApi.YbaApiVisibility.PUBLIC, sinceYBAVersion = "2.20.0")
   @AuthzPath
   public Result listBackups(UUID configUUID, String leaderAddr) {
     HighAvailabilityConfig config =

managed/src/main/java/com/yugabyte/yw/controllers/SessionController.java

@@ -181,13 +181,15 @@ public static class SessionInfo {
   }
 
   @ApiOperation(
+      notes = "Available since YBA version 2.20.0.",
       nickname = "getSessionInfo",
       value =
           "Get current user and customer uuid. This will not generate or return the API token, use"
               + " /api_token API for that.",
       authorizations = @Authorization(AbstractPlatformController.API_KEY_AUTH),
       response = SessionInfo.class)
   @With(TokenAuthenticator.class)
+  @YbaApi(visibility = YbaApi.YbaApiVisibility.PUBLIC, sinceYBAVersion = "2.20.0")
   @AuthzPath
   public Result getSessionInfo(Http.Request request) {
     Users user = CommonUtils.getUserFromContext();

managed/src/main/java/com/yugabyte/yw/forms/HAConfigGetResp.java

@@ -1,6 +1,7 @@
 /* Copyright 2024 YugabyteDB, Inc. and Contributors */
 package com.yugabyte.yw.forms;
 
+import com.fasterxml.jackson.annotation.JsonFormat;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.yugabyte.yw.common.HaConfigStates.GlobalState;
 import com.yugabyte.yw.models.HighAvailabilityConfig;
@@ -30,8 +31,9 @@ public String getClusterKey() {
     return haConfig.getClusterKey();
   }
 
-  @ApiModelProperty(value = "HA last failover")
+  @ApiModelProperty(value = "HA last failover", example = "2022-12-12T13:07:18Z")
   @JsonProperty("last_failover")
+  @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd'T'HH:mm:ss'Z'")
   public Date getLastFailover() {
     return haConfig.getLastFailover();
   }

managed/src/main/java/com/yugabyte/yw/models/HighAvailabilityConfig.java

@@ -12,9 +12,11 @@
 
 import static play.mvc.Http.Status.BAD_REQUEST;
 
+import com.fasterxml.jackson.annotation.JsonFormat;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import com.fasterxml.jackson.annotation.JsonSetter;
 import com.typesafe.config.ConfigValue;
 import com.typesafe.config.ConfigValueFactory;
 import com.yugabyte.yw.common.HaConfigStates.GlobalState;
@@ -26,6 +28,7 @@
 import com.yugabyte.yw.common.inject.StaticInjectorHolder;
 import io.ebean.Finder;
 import io.ebean.Model;
+import io.swagger.annotations.ApiModelProperty;
 import jakarta.persistence.CascadeType;
 import jakarta.persistence.Column;
 import jakarta.persistence.Entity;
@@ -70,7 +73,7 @@ public class HighAvailabilityConfig extends Model {
   @JsonProperty("cluster_key")
   private String clusterKey;
 
-  private Long lastFailover;
+  @JsonIgnore private Long lastFailover;
 
   @OneToMany(mappedBy = "config", cascade = CascadeType.ALL)
   private List<PlatformInstance> instances;
@@ -89,11 +92,19 @@ public void updateLastFailover() {
     this.update();
   }
 
+  @ApiModelProperty(value = "HA last failover", example = "2022-12-12T13:07:18Z")
   @JsonProperty("last_failover")
+  @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd'T'HH:mm:ss'Z'")
   public Date getLastFailover() {
     return (this.lastFailover != null) ? new Date(this.lastFailover) : null;
   }
 
+  @JsonSetter("last_failover")
+  @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd'T'HH:mm:ss'Z'")
+  public void setLastFailover(Date lastFailover) {
+    this.lastFailover = (lastFailover != null) ? lastFailover.getTime() : null;
+  }
+
   public void updateAcceptAnyCertificate(boolean acceptAnyCertificate) {
     this.acceptAnyCertificate = acceptAnyCertificate;
     this.update();

managed/src/main/java/com/yugabyte/yw/models/PlatformInstance.java

@@ -10,6 +10,7 @@
 
 package com.yugabyte.yw.models;
 
+import com.fasterxml.jackson.annotation.JsonFormat;
 import com.fasterxml.jackson.annotation.JsonGetter;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;
@@ -31,6 +32,7 @@
 import com.yugabyte.yw.common.inject.StaticInjectorHolder;
 import io.ebean.Finder;
 import io.ebean.Model;
+import io.swagger.annotations.ApiModelProperty;
 import jakarta.persistence.Column;
 import jakarta.persistence.Entity;
 import jakarta.persistence.Id;
@@ -76,7 +78,9 @@ public class PlatformInstance extends Model {
 
   @Constraints.Required
   @Temporal(TemporalType.TIMESTAMP)
+  @ApiModelProperty(value = "Last backup time", example = "2022-12-12T13:07:18Z")
   @JsonProperty("last_backup")
+  @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd'T'HH:mm:ss'Z'")
   private Date lastBackup;
 
   @Constraints.Required()