From d145e3b3979afab9f87caebf87ba820fcffb7701 Mon Sep 17 00:00:00 2001 From: "Wang, Fei" Date: Sat, 28 Dec 2024 17:17:06 -0800 Subject: [PATCH] desc ApiResponse description to Operation description --- .../master/http/api/ApiMasterResource.scala | 44 +++++++++--------- .../http/api/v1/ApplicationResource.scala | 19 ++++---- .../master/http/api/v1/MasterResource.scala | 7 +-- .../master/http/api/v1/RatisResource.scala | 45 ++++++++++--------- .../master/http/api/v1/ShuffleResource.scala | 8 ++-- .../master/http/api/v1/WorkerResource.scala | 27 +++++------ .../common/http/api/ApiBaseResource.scala | 45 ++++++++++--------- .../http/api/v1/ApiV1BaseResource.scala | 9 ++-- .../common/http/api/v1/ConfResource.scala | 17 +++---- .../common/http/api/v1/LoggerResource.scala | 10 ++--- .../worker/http/api/ApiWorkerResource.scala | 29 ++++++------ .../http/api/v1/ApplicationResource.scala | 7 +-- .../worker/http/api/v1/ShuffleResource.scala | 12 ++--- .../worker/http/api/v1/WorkerResource.scala | 18 ++++---- 14 files changed, 156 insertions(+), 141 deletions(-) diff --git a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/ApiMasterResource.scala b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/ApiMasterResource.scala index 447a9b1b233..26899da5530 100644 --- a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/ApiMasterResource.scala +++ b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/ApiMasterResource.scala @@ -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 @@ -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, @@ -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, diff --git a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/ApplicationResource.scala b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/ApplicationResource.scala index 0cfa5f4b6f3..27d2efa0f1c 100644 --- a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/ApplicationResource.scala +++ b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/ApplicationResource.scala @@ -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 @@ -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() @@ -53,12 +54,12 @@ 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 @@ -66,26 +67,26 @@ class ApplicationResource extends ApiRequestContext { 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 diff --git a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/MasterResource.scala b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/MasterResource.scala index 000a86f3214..727adc0a9e3 100644 --- a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/MasterResource.scala +++ b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/MasterResource.scala @@ -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 @@ -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) { diff --git a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/RatisResource.scala b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/RatisResource.scala index 7447a461e87..e18ae1edcef 100644 --- a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/RatisResource.scala +++ b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/RatisResource.scala @@ -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 @@ -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)) @@ -62,12 +63,12 @@ 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)) @@ -75,13 +76,13 @@ class RatisResource extends ApiRequestContext with Logging { 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)) @@ -89,12 +90,12 @@ class RatisResource extends ApiRequestContext with Logging { 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)) @@ -102,12 +103,12 @@ class RatisResource extends ApiRequestContext with Logging { 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)) @@ -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)) @@ -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)) @@ -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)) @@ -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)) @@ -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)) diff --git a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/ShuffleResource.scala b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/ShuffleResource.scala index fbdcd920ecf..ba6ca4cf8c5 100644 --- a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/ShuffleResource.scala +++ b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/ShuffleResource.scala @@ -23,6 +23,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 @@ -36,13 +37,14 @@ import org.apache.celeborn.service.deploy.master.Master @Consumes(Array(MediaType.APPLICATION_JSON)) class ShuffleResource extends ApiRequestContext { private def statusSystem = httpService.asInstanceOf[Master].statusSystem + + @Operation(description = + "List all running shuffle keys of the service. It will return all running shuffle's key of the cluster.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[ShufflesResponse]))), - description = - "List all running shuffle keys of the service. It will return all running shuffle's key of the cluster.") + schema = new Schema(implementation = classOf[ShufflesResponse])))) @GET def shuffles: ShufflesResponse = { val shuffles = new util.ArrayList[String]() diff --git a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/WorkerResource.scala b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/WorkerResource.scala index ae8a602f339..a461b8dac78 100644 --- a/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/WorkerResource.scala +++ b/master/src/main/scala/org/apache/celeborn/service/deploy/master/http/api/v1/WorkerResource.scala @@ -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 @@ -41,13 +42,13 @@ class WorkerResource extends ApiRequestContext { private def master: Master = httpService.asInstanceOf[Master] private def statusSystem = master.statusSystem + @Operation(description = + "List worker information of the service. It will list all registered workers' information.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[WorkersResponse]))), - description = - "List worker information of the service. It will list all registered workers' information.") + schema = new Schema(implementation = classOf[WorkersResponse])))) @GET def workers: WorkersResponse = { new WorkersResponse() @@ -66,13 +67,13 @@ class WorkerResource extends ApiRequestContext { ApiUtils.workerData).toSeq.asJava) } + @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.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[HandleResponse]))), - 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.") + schema = new Schema(implementation = classOf[HandleResponse])))) @POST @Path("/exclude") def excludeWorker(request: ExcludeWorkerRequest): HandleResponse = ensureMasterIsLeader(master) { @@ -82,12 +83,12 @@ class WorkerResource extends ApiRequestContext { new HandleResponse().success(success).message(msg) } + @Operation(description = "Remove the workers unavailable info from the master.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[HandleResponse]))), - description = "Remove the workers unavailable info from the master.") + schema = new Schema(implementation = classOf[HandleResponse])))) @POST @Path("/remove_unavailable") def removeWorkersUnavailableInfo(request: RemoveWorkersUnavailableInfoRequest): HandleResponse = @@ -97,13 +98,13 @@ class WorkerResource extends ApiRequestContext { new HandleResponse().success(success).message(msg) } + @Operation(description = "List all worker event infos of the master.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, schema = new Schema( - implementation = classOf[WorkerEventsResponse]))), - description = "List all worker event infos of the master.") + implementation = classOf[WorkerEventsResponse])))) @GET @Path("/events") def workerEvents(): WorkerEventsResponse = { @@ -118,13 +119,13 @@ class WorkerResource extends ApiRequestContext { }.toSeq.asJava) } + @Operation(description = + "For Master(Leader) can send worker event to manager workers. Legal types are 'NONE', 'IMMEDIATELY', 'DECOMMISSION', 'DECOMMISSIONTHENIDLE', 'GRACEFUL', 'RECOMMISSION'.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[HandleResponse]))), - description = - "For Master(Leader) can send worker event to manager workers. Legal types are 'NONE', 'IMMEDIATELY', 'DECOMMISSION', 'DECOMMISSIONTHENIDLE', 'GRACEFUL', 'RECOMMISSION'.") + schema = new Schema(implementation = classOf[HandleResponse])))) @POST @Path("/events") def sendWorkerEvents(request: SendWorkerEventRequest): HandleResponse = diff --git a/service/src/main/scala/org/apache/celeborn/server/common/http/api/ApiBaseResource.scala b/service/src/main/scala/org/apache/celeborn/server/common/http/api/ApiBaseResource.scala index 03dbe69ce10..c9fc275953f 100644 --- a/service/src/main/scala/org/apache/celeborn/server/common/http/api/ApiBaseResource.scala +++ b/service/src/main/scala/org/apache/celeborn/server/common/http/api/ApiBaseResource.scala @@ -20,6 +20,7 @@ package org.apache.celeborn.server.common.http.api import javax.ws.rs.{GET, Path, Produces, QueryParam} 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 @@ -35,24 +36,24 @@ private[api] class ApiBaseResource extends ApiRequestContext { def ping(): String = "pong" @Path("/conf") + @Operation(description = "List the conf setting.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = "List the conf setting.") + mediaType = MediaType.TEXT_PLAIN))) @GET def conf: String = httpService.getConf @Path("/listDynamicConfigs") + @Operation(description = "List the dynamic configs. " + + "The parameter level specifies the config level of dynamic configs. " + + "The parameter tenant specifies the tenant id of TENANT or TENANT_USER level. " + + "The parameter name specifies the user name of TENANT_USER level. " + + "Meanwhile, either none or all of the parameter tenant and name are specified for TENANT_USER level.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = "List the dynamic configs. " + - "The parameter level specifies the config level of dynamic configs. " + - "The parameter tenant specifies the tenant id of TENANT or TENANT_USER level. " + - "The parameter name specifies the user name of TENANT_USER level. " + - "Meanwhile, either none or all of the parameter tenant and name are specified for TENANT_USER level.") + mediaType = MediaType.TEXT_PLAIN))) @GET def listDynamicConfigs( @QueryParam("level") level: String, @@ -65,50 +66,50 @@ private[api] class ApiBaseResource extends ApiRequestContext { } @Path("/workerInfo") + @Operation(description = + "For MASTER: List worker information of the service. It will list all registered workers' information.\n" + + "For WORKER: List the worker information of the worker.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = - "For MASTER: List worker information of the service. It will list all registered workers' information.\n" + - "For WORKER: List the worker information of the worker.") + mediaType = MediaType.TEXT_PLAIN))) @GET def workerInfo(): String = { httpService.getWorkerInfo } @Path("/threadDump") + @Operation(description = "List the current thread dump.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = "List the current thread dump.") + mediaType = MediaType.TEXT_PLAIN))) @GET def threadDump(): String = { httpService.getThreadDump } @Path("shuffle") + @Operation(description = + "For MASTER: List all running shuffle keys of the service. It will return all running shuffle's key of the cluster.\n" + + "For WORKER: List all the running shuffle keys of the worker. It only return keys of shuffles running in that worker.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = - "For MASTER: List all running shuffle keys of the service. It will return all running shuffle's key of the cluster.\n" + - "For WORKER: List all the running shuffle keys of the worker. It only return keys of shuffles running in that worker.") + mediaType = MediaType.TEXT_PLAIN))) @GET def shuffles(): String = { httpService.getShuffleList } @Path("applications") + @Operation(description = + "For MASTER: List all running application's ids of the cluster.\n" + + "For WORKER: List all running application's ids of the worker. It only return application ids running in that worker.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = - "For MASTER: List all running application's ids of the cluster.\n" + - "For WORKER: List all running application's ids of the worker. It only return application ids running in that worker.") + mediaType = MediaType.TEXT_PLAIN))) @GET def applications(): String = { httpService.getApplicationList diff --git a/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/ApiV1BaseResource.scala b/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/ApiV1BaseResource.scala index 110aeaffb2c..210921f5ce9 100644 --- a/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/ApiV1BaseResource.scala +++ b/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/ApiV1BaseResource.scala @@ -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 @@ -39,13 +40,13 @@ class ApiV1BaseResource extends ApiRequestContext { def logger: Class[LoggerResource] = classOf[LoggerResource] @Path("/thread_dump") + @Operation(description = "List the current thread dump.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, schema = new Schema( - implementation = classOf[ThreadStackResponse]))), - description = "List the current thread dump.") + implementation = classOf[ThreadStackResponse])))) @GET @Produces(Array(MediaType.APPLICATION_JSON)) def threadDump(): ThreadStackResponse = { @@ -70,13 +71,13 @@ class ApiV1BaseResource extends ApiRequestContext { } @Path("/container_info") + @Operation(description = "List the container info.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, schema = new Schema( - implementation = classOf[ContainerInfo]))), - description = "List the container info.") + implementation = classOf[ContainerInfo])))) @GET @Produces(Array(MediaType.APPLICATION_JSON)) def containerInfo(): ContainerInfo = diff --git a/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/ConfResource.scala b/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/ConfResource.scala index d24e6615475..83b80c4833e 100644 --- a/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/ConfResource.scala +++ b/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/ConfResource.scala @@ -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 @@ -40,12 +41,12 @@ import org.apache.celeborn.server.common.service.config.ConfigLevel private[api] class ConfResource extends ApiRequestContext { private def configService = httpService.configService + @Operation(description = "List the conf setting") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[ConfResponse]))), - description = "List the conf setting") + schema = new Schema(implementation = classOf[ConfResponse])))) @GET def conf: ConfResponse = { new ConfResponse() @@ -55,16 +56,16 @@ private[api] class ConfResource extends ApiRequestContext { }.asJava) } + @Operation(description = "List the dynamic configs. " + + "The parameter level specifies the config level of dynamic configs. " + + "The parameter tenant specifies the tenant id of TENANT or TENANT_USER level. " + + "The parameter name specifies the user name of TENANT_USER level. " + + "Meanwhile, either none or all of the parameter tenant and name are specified for TENANT_USER level.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[DynamicConfigResponse]))), - description = "List the dynamic configs. " + - "The parameter level specifies the config level of dynamic configs. " + - "The parameter tenant specifies the tenant id of TENANT or TENANT_USER level. " + - "The parameter name specifies the user name of TENANT_USER level. " + - "Meanwhile, either none or all of the parameter tenant and name are specified for TENANT_USER level.") + schema = new Schema(implementation = classOf[DynamicConfigResponse])))) @GET @Path("/dynamic") def dynamicConf( diff --git a/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/LoggerResource.scala b/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/LoggerResource.scala index 641debbfed8..e75d338106e 100644 --- a/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/LoggerResource.scala +++ b/service/src/main/scala/org/apache/celeborn/server/common/http/api/v1/LoggerResource.scala @@ -22,7 +22,7 @@ import javax.ws.rs.core.MediaType import scala.collection.JavaConverters._ -import io.swagger.v3.oas.annotations.Parameter +import io.swagger.v3.oas.annotations.{Operation, Parameter} 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 @@ -38,12 +38,12 @@ import org.apache.celeborn.server.common.http.api.ApiRequestContext @Consumes(Array(MediaType.APPLICATION_JSON)) class LoggerResource extends ApiRequestContext { + @Operation(description = "Get the logger level, return all loggers if no name specified.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[LoggerInfo]))), - description = "Get the logger level, return all loggers if no name specified.") + schema = new Schema(implementation = classOf[LoggerInfo])))) @GET def getLoggerLevel( @QueryParam("name") name: String, @@ -69,12 +69,12 @@ class LoggerResource extends ApiRequestContext { } } + @Operation(description = "Set the logger level.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[HandleResponse]))), - description = "Set the logger level.") + schema = new Schema(implementation = classOf[HandleResponse])))) @POST def setLoggerLevel(request: LoggerInfo): HandleResponse = { val loggerName = request.getName diff --git a/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/ApiWorkerResource.scala b/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/ApiWorkerResource.scala index a116fb950a0..087bc89e327 100644 --- a/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/ApiWorkerResource.scala +++ b/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/ApiWorkerResource.scala @@ -20,6 +20,7 @@ package org.apache.celeborn.service.deploy.worker.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 @@ -31,58 +32,58 @@ import org.apache.celeborn.server.common.http.api.ApiRequestContext class ApiWorkerResource extends ApiRequestContext { @Path("/listPartitionLocationInfo") + @Operation(description = "List all the living PartitionLocation information in that worker.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = "List all the living PartitionLocation information in that worker.") + mediaType = MediaType.TEXT_PLAIN))) @GET def listPartitionLocationInfo: String = httpService.listPartitionLocationInfo @Path("/unavailablePeers") + @Operation(description = + "List the unavailable peers of the worker, this always means the worker connect to the peer failed.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = - "List the unavailable peers of the worker, this always means the worker connect to the peer failed.") + mediaType = MediaType.TEXT_PLAIN))) @GET def unavailablePeers: String = httpService.getUnavailablePeers @Path("/isShutdown") + @Operation(description = "Show if the worker is during the process of shutdown.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = "Show if the worker is during the process of shutdown.") + mediaType = MediaType.TEXT_PLAIN))) @GET def isShutdown: String = httpService.isShutdown @Path("/isDecommissioning") + @Operation(description = "Show if the worker is during the process of decommission.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = "Show if the worker is during the process of decommission.") + mediaType = MediaType.TEXT_PLAIN))) @GET def isDecommissioning: String = httpService.isDecommissioning @Path("/isRegistered") + @Operation(description = "Show if the worker is registered to the master success.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.TEXT_PLAIN)), - description = "Show if the worker is registered to the master success.") + mediaType = MediaType.TEXT_PLAIN))) @GET def isRegistered: String = httpService.isRegistered @Path("/exit") + @Operation(description = + "Trigger this worker to exit. Legal types are 'Decommission', 'Graceful' and 'Immediately'.") @ApiResponse( responseCode = "200", content = Array(new Content( - mediaType = MediaType.APPLICATION_FORM_URLENCODED)), - description = - "Trigger this worker to exit. Legal types are 'Decommission', 'Graceful' and 'Immediately'.") + mediaType = MediaType.APPLICATION_FORM_URLENCODED))) @POST def exit(@FormParam("type") exitType: String): String = { httpService.exit(normalizeParam(exitType)) diff --git a/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/ApplicationResource.scala b/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/ApplicationResource.scala index 0020f5367f0..8b4911bc2ca 100644 --- a/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/ApplicationResource.scala +++ b/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/ApplicationResource.scala @@ -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 @@ -36,13 +37,13 @@ import org.apache.celeborn.service.deploy.worker.Worker class ApplicationResource extends ApiRequestContext { private def worker = httpService.asInstanceOf[Worker] + @Operation(description = + "List all running application's ids of the worker. It only return application ids running in that worker.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[ApplicationsResponse]))), - description = - "List all running application's ids of the worker. It only return application ids running in that worker.") + schema = new Schema(implementation = classOf[ApplicationsResponse])))) @GET def applications(): ApplicationsResponse = { new ApplicationsResponse() diff --git a/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/ShuffleResource.scala b/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/ShuffleResource.scala index ef43b4ca34f..f4b6a31f554 100644 --- a/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/ShuffleResource.scala +++ b/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/ShuffleResource.scala @@ -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 @@ -37,13 +38,13 @@ import org.apache.celeborn.service.deploy.worker.Worker class ShuffleResource extends ApiRequestContext { private def worker = httpService.asInstanceOf[Worker] + @Operation(description = + "List all the running shuffle keys of the worker. It only return keys of shuffles running in that worker.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[ShufflesResponse]))), - description = - "List all the running shuffle keys of the worker. It only return keys of shuffles running in that worker.") + schema = new Schema(implementation = classOf[ShufflesResponse])))) @GET def shuffles(): ShufflesResponse = { new ShufflesResponse() @@ -51,13 +52,14 @@ class ShuffleResource extends ApiRequestContext { } + @Operation(description = + "List all the living shuffle PartitionLocation information in the worker.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, schema = new Schema( - implementation = classOf[ShufflePartitionsResponse]))), - description = "List all the living shuffle PartitionLocation information in the worker.") + implementation = classOf[ShufflePartitionsResponse])))) @GET @Path("/partitions") def partitions(): ShufflePartitionsResponse = { diff --git a/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/WorkerResource.scala b/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/WorkerResource.scala index 24e2b39f856..38a745a432b 100644 --- a/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/WorkerResource.scala +++ b/worker/src/main/scala/org/apache/celeborn/service/deploy/worker/http/api/v1/WorkerResource.scala @@ -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 @@ -37,13 +38,13 @@ import org.apache.celeborn.service.deploy.worker.Worker class WorkerResource extends ApiRequestContext { private def worker = httpService.asInstanceOf[Worker] + @Operation(description = "List the worker information.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, schema = new Schema( - implementation = classOf[WorkerInfoResponse]))), - description = "List the worker information.") + implementation = classOf[WorkerInfoResponse])))) @GET def workers(): WorkerInfoResponse = { ApiUtils.workerInfoResponse( @@ -53,13 +54,13 @@ class WorkerResource extends ApiRequestContext { worker.registered.get()) } + @Operation(description = + "List the unavailable peers of the worker, this always means the worker connect to the peer failed.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema(implementation = classOf[UnAvailablePeersResponse]))), - description = - "List the unavailable peers of the worker, this always means the worker connect to the peer failed.") + schema = new Schema(implementation = classOf[UnAvailablePeersResponse])))) @GET @Path("/unavailable_peers") def unavailablePeerWorkers(): UnAvailablePeersResponse = { @@ -70,14 +71,13 @@ class WorkerResource extends ApiRequestContext { }.toSeq.asJava) } + @Operation(description = + "Trigger this worker to exit. Legal exit types are 'DECOMMISSION', 'GRACEFUL' and 'IMMEDIATELY'.") @ApiResponse( responseCode = "200", content = Array(new Content( mediaType = MediaType.APPLICATION_JSON, - schema = new Schema( - implementation = classOf[HandleResponse]))), - description = - "Trigger this worker to exit. Legal exit types are 'DECOMMISSION', 'GRACEFUL' and 'IMMEDIATELY'.") + schema = new Schema(implementation = classOf[HandleResponse])))) @POST @Path("exit") def exit(request: WorkerExitRequest): HandleResponse = {