Skip to content

Commit

Permalink
desc
Browse files Browse the repository at this point in the history 
ApiResponse description to Operation description
  • Loading branch information
@turboFei
turboFei committed Jan 13, 2025
1 parent eb950c8 commit d145e3b
Show file tree
Hide file tree
Showing 14 changed files with 156 additions and 141 deletions.
44 changes: 23 additions & 21 deletions ...src/main/scala/org/apache/celeborn/service/deploy/master/http/api/ApiMasterResource.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ package org.apache.celeborn.service.deploy.master.http.api
import javax.ws.rs.{FormParam, GET, Path, POST}
import javax.ws.rs.core.MediaType

import io.swagger.v3.oas.annotations.Operation
import io.swagger.v3.oas.annotations.media.Content
import io.swagger.v3.oas.annotations.responses.ApiResponse
import io.swagger.v3.oas.annotations.tags.Tag
Expand All @@ -34,76 +35,77 @@ import org.apache.celeborn.server.common.http.api.ApiRequestContext
class ApiMasterResource extends ApiRequestContext {

@Path("/masterGroupInfo")
@Operation(description =
"List master group information of the service. It will list all master's LEADER, FOLLOWER information.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.TEXT_PLAIN)),
description =
"List master group information of the service. It will list all master's LEADER, FOLLOWER information.")
mediaType = MediaType.TEXT_PLAIN)))
@GET
def masterGroupInfo: String = httpService.getMasterGroupInfo

@Path("/lostWorkers")
@Operation(description = "List all lost workers of the master.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.TEXT_PLAIN)),
description = "List all lost workers of the master.")
mediaType = MediaType.TEXT_PLAIN)))
@GET
def lostWorkers: String = httpService.getLostWorkers

@Path("/excludedWorkers")
@Operation(description = "List all excluded workers of the master.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.TEXT_PLAIN)),
description = "List all excluded workers of the master.")
mediaType = MediaType.TEXT_PLAIN)))
@GET
def excludedWorkers: String = httpService.getExcludedWorkers

@Path("/shutdownWorkers")
@Operation(description = "List all shutdown workers of the master.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.TEXT_PLAIN)),
description = "List all shutdown workers of the master.")
mediaType = MediaType.TEXT_PLAIN)))
@GET
def shutdownWorkers: String = httpService.getShutdownWorkers

@Path("/decommissionWorkers")
@Operation(description = "List all decommission workers of the master.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.TEXT_PLAIN)),
description = "List all decommission workers of the master.")
mediaType = MediaType.TEXT_PLAIN)))
@GET
def decommissionWorkers: String = httpService.getDecommissionWorkers

@Path("/hostnames")
@Operation(description =
"List all running application's LifecycleManager's hostnames of the cluster.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.TEXT_PLAIN)),
description = "List all running application's LifecycleManager's hostnames of the cluster.")
mediaType = MediaType.TEXT_PLAIN)))
@GET
def hostnames: String = httpService.getHostnameList

@Path("/workerEventInfo")
@Operation(description = "List all worker event infos of the master.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.TEXT_PLAIN)),
description = "List all worker event infos of the master.")
mediaType = MediaType.TEXT_PLAIN)))
@GET
def workerEventInfo: String = httpService.getWorkerEventInfo()

@Path("/exclude")
@Operation(description =
"Excluded workers of the master add or remove the worker manually given worker id. The parameter add or remove specifies the excluded workers to add or remove, which value is separated by commas.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_FORM_URLENCODED)),
description =
"Excluded workers of the master add or remove the worker manually given worker id. The parameter add or remove specifies the excluded workers to add or remove, which value is separated by commas.")
mediaType = MediaType.APPLICATION_FORM_URLENCODED)))
@POST
def exclude(
@FormParam("add") addWorkers: String,
Expand All @@ -120,12 +122,12 @@ class ApiMasterResource extends ApiRequestContext {
}

@Path("/sendWorkerEvent")
@Operation(description =
"For Master(Leader) can send worker event to manager workers. Legal types are 'None', 'Immediately', 'Decommission', 'DecommissionThenIdle', 'Graceful', 'Recommission', and the parameter workers is separated by commas.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_FORM_URLENCODED)),
description =
"For Master(Leader) can send worker event to manager workers. Legal types are 'None', 'Immediately', 'Decommission', 'DecommissionThenIdle', 'Graceful', 'Recommission', and the parameter workers is separated by commas.")
mediaType = MediaType.APPLICATION_FORM_URLENCODED)))
@POST
def sendWorkerEvent(
@FormParam("type") eventType: String,
Expand Down
19 changes: 10 additions & 9 deletions ...ain/scala/org/apache/celeborn/service/deploy/master/http/api/v1/ApplicationResource.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ import javax.ws.rs.core.MediaType

import scala.collection.JavaConverters._

import io.swagger.v3.oas.annotations.Operation
import io.swagger.v3.oas.annotations.media.{Content, Schema}
import io.swagger.v3.oas.annotations.responses.ApiResponse
import io.swagger.v3.oas.annotations.tags.Tag
Expand All @@ -36,12 +37,12 @@ import org.apache.celeborn.service.deploy.master.Master
class ApplicationResource extends ApiRequestContext {
private def statusSystem = httpService.asInstanceOf[Master].statusSystem

@Operation(description = "List all running application's ids of the cluster.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[ApplicationsHeartbeatResponse]))),
description = "List all running application's ids of the cluster.")
schema = new Schema(implementation = classOf[ApplicationsHeartbeatResponse]))))
@GET
def applications(): ApplicationsHeartbeatResponse = {
new ApplicationsHeartbeatResponse()
Expand All @@ -53,39 +54,39 @@ class ApplicationResource extends ApiRequestContext {
}.toSeq.asJava)
}

@Operation(description = "Delete resource of apps.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HandleResponse]))),
description = "Delete resource of apps.")
schema = new Schema(implementation = classOf[HandleResponse]))))
@DELETE
def deleteApps(request: DeleteAppsRequest): HandleResponse = {
val apps = request.getApps.asScala
apps.foreach(app => statusSystem.deleteApp(app))
new HandleResponse().success(true).message(s"deleted shuffles of app ${apps}")
}

@Operation(description =
"List all running application's LifecycleManager's hostnames of the cluster.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HostnamesResponse]))),
description =
"List all running application's LifecycleManager's hostnames of the cluster.")
schema = new Schema(implementation = classOf[HostnamesResponse]))))
@GET
@Path("/hostnames")
def hostnames(): HostnamesResponse = {
new HostnamesResponse().hostnames(statusSystem.hostnameSet.asScala.toSeq.asJava)
}

@Operation(description = "Revise lost shuffles or deleted shuffles of an application.")
@Path("/revise_lost_shuffles")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HandleResponse]))),
description = "Revise lost shuffles or deleted shuffles of an application.")
schema = new Schema(implementation = classOf[HandleResponse]))))
@POST
def reviseLostShuffles(request: ReviseLostShufflesRequest): HandleResponse = {
val appId = request.getAppId
Expand Down
7 changes: 4 additions & 3 deletions ...src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/MasterResource.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ import javax.ws.rs.core.MediaType

import scala.collection.JavaConverters._

import io.swagger.v3.oas.annotations.Operation
import io.swagger.v3.oas.annotations.media.{Content, Schema}
import io.swagger.v3.oas.annotations.responses.ApiResponse
import io.swagger.v3.oas.annotations.tags.Tag
Expand All @@ -38,13 +39,13 @@ import org.apache.celeborn.service.deploy.master.clustermeta.ha.HAMasterMetaMana
class MasterResource extends ApiRequestContext {
private def master = httpService.asInstanceOf[Master]

@Operation(description =
"List master group information of the service. It will list all master's LEADER, FOLLOWER information.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[MasterInfoResponse]))),
description =
"List master group information of the service. It will list all master's LEADER, FOLLOWER information.")
schema = new Schema(implementation = classOf[MasterInfoResponse]))))
@GET
def masterGroupInfo: MasterInfoResponse = {
if (master.conf.haEnabled) {
Expand Down
45 changes: 23 additions & 22 deletions .../src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/RatisResource.scala
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import javax.ws.rs.core.{MediaType, Response}

import scala.collection.JavaConverters._

import io.swagger.v3.oas.annotations.Operation
import io.swagger.v3.oas.annotations.media.{Content, Schema}
import io.swagger.v3.oas.annotations.responses.ApiResponse
import io.swagger.v3.oas.annotations.tags.Tag
Expand All @@ -48,12 +49,12 @@ class RatisResource extends ApiRequestContext with Logging {
private def master = httpService.asInstanceOf[Master]
private def ratisServer = master.statusSystem.asInstanceOf[HAMasterMetaManager].getRatisServer

@Operation(description = "Transfer the group leader to the specified server.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HandleResponse]))),
description = "Transfer the group leader to the specified server.")
schema = new Schema(implementation = classOf[HandleResponse]))))
@POST
@Path("/election/transfer")
@Produces(Array(MediaType.APPLICATION_JSON))
Expand All @@ -62,52 +63,52 @@ class RatisResource extends ApiRequestContext with Logging {
transferLeadership(request.getPeerAddress)
}

@Operation(description = "Make the group leader step down its leadership.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HandleResponse]))),
description = "Make the group leader step down its leadership.")
schema = new Schema(implementation = classOf[HandleResponse]))))
@POST
@Path("/election/step_down")
@Produces(Array(MediaType.APPLICATION_JSON))
def electionStepDown(): HandleResponse = ensureMasterIsLeader(master) {
transferLeadership(null)
}

@Operation(description = "Pause leader election at the current server." +
" Then, the current server would not start a leader election.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HandleResponse]))),
description = "Pause leader election at the current server." +
" Then, the current server would not start a leader election.")
schema = new Schema(implementation = classOf[HandleResponse]))))
@POST
@Path("/election/pause")
@Produces(Array(MediaType.APPLICATION_JSON))
def electionPause(): HandleResponse = ensureMasterHAEnabled(master) {
applyElectionOp(new LeaderElectionManagementRequest.Pause)
}

@Operation(description = "Resume leader election at the current server.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HandleResponse]))),
description = "Resume leader election at the current server.")
schema = new Schema(implementation = classOf[HandleResponse]))))
@POST
@Path("/election/resume")
@Produces(Array(MediaType.APPLICATION_JSON))
def electionResume(): HandleResponse = ensureMasterHAEnabled(master) {
applyElectionOp(new LeaderElectionManagementRequest.Resume)
}

@Operation(description = "Add new peers to the raft group.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HandleResponse]))),
description = "Add new peers to the raft group.")
schema = new Schema(implementation = classOf[HandleResponse]))))
@POST
@Path("/peer/add")
@Produces(Array(MediaType.APPLICATION_JSON))
Expand Down Expand Up @@ -148,12 +149,12 @@ class RatisResource extends ApiRequestContext with Logging {
}
}

@Operation(description = "Remove peers from the raft group.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HandleResponse]))),
description = "Remove peers from the raft group.")
schema = new Schema(implementation = classOf[HandleResponse]))))
@POST
@Path("/peer/remove")
@Produces(Array(MediaType.APPLICATION_JSON))
Expand Down Expand Up @@ -186,12 +187,12 @@ class RatisResource extends ApiRequestContext with Logging {
}
}

@Operation(description = "Set the priority of the peers in the raft group.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HandleResponse]))),
description = "Set the priority of the peers in the raft group.")
schema = new Schema(implementation = classOf[HandleResponse]))))
@POST
@Path("/peer/set_priority")
@Produces(Array(MediaType.APPLICATION_JSON))
Expand Down Expand Up @@ -222,12 +223,12 @@ class RatisResource extends ApiRequestContext with Logging {
}
}

@Operation(description = "Trigger the current server to take snapshot.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_JSON,
schema = new Schema(implementation = classOf[HandleResponse]))),
description = "Trigger the current server to take snapshot.")
schema = new Schema(implementation = classOf[HandleResponse]))))
@POST
@Path("/snapshot/create")
@Produces(Array(MediaType.APPLICATION_JSON))
Expand All @@ -248,12 +249,12 @@ class RatisResource extends ApiRequestContext with Logging {
}
}

@Operation(description = "Get the raft-meta.conf file of the current server.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_OCTET_STREAM,
schema = new Schema(implementation = classOf[Response]))),
description = "Get the raft-meta.conf file of the current server.")
schema = new Schema(implementation = classOf[Response]))))
@GET
@Path("/local/raft_meta_conf")
@Produces(Array(MediaType.APPLICATION_OCTET_STREAM))
Expand All @@ -273,13 +274,13 @@ class RatisResource extends ApiRequestContext with Logging {
.build()
}

@Operation(description = "Generate a new-raft-meta.conf file based on original raft-meta.conf" +
" and new peers, which is used to move a raft node to a new node.")
@ApiResponse(
responseCode = "200",
content = Array(new Content(
mediaType = MediaType.APPLICATION_OCTET_STREAM,
schema = new Schema(implementation = classOf[Response]))),
description = "Generate a new-raft-meta.conf file based on original raft-meta.conf" +
" and new peers, which is used to move a raft node to a new node.")
schema = new Schema(implementation = classOf[Response]))))
@POST
@Path("/local/raft_meta_conf")
@Produces(Array(MediaType.APPLICATION_OCTET_STREAM))
Expand Down
Loading

0 comments on commit d145e3b

Please sign in to comment.