Skip to content

Commit ac2a114

Browse files
spboltonspbolton
committed
Batch 4 resources
1 parent b55504d commit ac2a114

16 files changed

Lines changed: 2802 additions & 354 deletions

‎dotCMS/src/main/java/com/dotcms/rest/CMSConfigResource.java‎

Lines changed: 186 additions & 28 deletions
Large diffs are not rendered by default.

‎dotCMS/src/main/java/com/dotcms/rest/ClusterResource.java‎

Lines changed: 104 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
import javax.ws.rs.PathParam;
1414
import javax.ws.rs.Produces;
1515
import javax.ws.rs.core.Context;
16+
import javax.ws.rs.core.MediaType;
1617
import javax.ws.rs.core.Response;
1718
import com.dotcms.cluster.bean.Server;
1819
import com.dotcms.cluster.bean.ServerPort;
@@ -34,9 +35,17 @@
3435
import com.dotmarketing.util.UtilMethods;
3536
import com.dotmarketing.util.json.JSONException;
3637
import com.dotmarketing.util.json.JSONObject;
38+
import com.dotcms.rest.annotation.SwaggerCompliant;
39+
import io.swagger.v3.oas.annotations.Operation;
40+
import io.swagger.v3.oas.annotations.Parameter;
41+
import io.swagger.v3.oas.annotations.media.Content;
42+
import io.swagger.v3.oas.annotations.media.Schema;
43+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
44+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
3745
import io.swagger.v3.oas.annotations.tags.Tag;
3846

3947

48+
@SwaggerCompliant(value = "System administration and configuration APIs", batch = 4)
4049
@Path("/cluster")
4150
@Tag(name = "Cluster Management")
4251
public class ClusterResource {
@@ -55,10 +64,30 @@ public class ClusterResource {
5564
* @throws DotCacheException
5665
* @throws DotSecurityException
5766
*/
67+
@Operation(
68+
summary = "Get cluster nodes status",
69+
description = "Returns a map of cache cluster nodes status including server health information and cluster state. Validates cache transport across all cluster members."
70+
)
71+
@ApiResponses(value = {
72+
@ApiResponse(responseCode = "200",
73+
description = "Cluster nodes status retrieved successfully",
74+
content = @Content(mediaType = "application/json",
75+
schema = @Schema(implementation = ResponseEntityMapView.class))),
76+
@ApiResponse(responseCode = "401",
77+
description = "Unauthorized - backend user authentication required",
78+
content = @Content(mediaType = "application/json")),
79+
@ApiResponse(responseCode = "403",
80+
description = "Forbidden - insufficient permissions to access configuration portlet",
81+
content = @Content(mediaType = "application/json")),
82+
@ApiResponse(responseCode = "500",
83+
description = "Internal server error retrieving cluster status",
84+
content = @Content(mediaType = "application/json"))
85+
})
5886
@GET
5987
@Path ("/getNodesStatus/{params:.*}")
6088
@Produces ("application/json")
61-
public Response getNodesInfo (@Context HttpServletRequest request, @Context final HttpServletResponse response, @PathParam ("params") String params )
89+
public Response getNodesInfo (@Context HttpServletRequest request, @Context final HttpServletResponse response,
90+
@Parameter(description = "URL parameters for the cluster status request", required = true) @PathParam ("params") String params )
6291
throws DotDataException, JSONException, DotStateException, DotSecurityException, DotCacheException {
6392

6493
new WebResource.InitBuilder(webResource)
@@ -112,10 +141,30 @@ public Response getNodesInfo (@Context HttpServletRequest request, @Context fina
112141
* @throws DotDataException
113142
* @throws JSONException
114143
*/
144+
@Operation(
145+
summary = "Get Elasticsearch configuration properties",
146+
description = "Returns Elasticsearch cluster configuration properties including bind address, cache port, and Elasticsearch transport TCP port for the current server."
147+
)
148+
@ApiResponses(value = {
149+
@ApiResponse(responseCode = "200",
150+
description = "Elasticsearch configuration properties retrieved successfully",
151+
content = @Content(mediaType = "application/json",
152+
schema = @Schema(implementation = ResponseEntityStringView.class))),
153+
@ApiResponse(responseCode = "401",
154+
description = "Unauthorized - backend user authentication required",
155+
content = @Content(mediaType = "application/json")),
156+
@ApiResponse(responseCode = "403",
157+
description = "Forbidden - insufficient permissions to access configuration portlet",
158+
content = @Content(mediaType = "application/json")),
159+
@ApiResponse(responseCode = "500",
160+
description = "Internal server error retrieving ES configuration",
161+
content = @Content(mediaType = "application/json"))
162+
})
115163
@GET
116164
@Path ("/getESConfigProperties/{params:.*}")
117165
@Produces ("application/json")
118-
public Response getESConfigProperties ( @Context HttpServletRequest request, @Context final HttpServletResponse response, @PathParam ("params") String params )
166+
public Response getESConfigProperties ( @Context HttpServletRequest request, @Context final HttpServletResponse response,
167+
@Parameter(description = "URL parameters for the ES configuration request", required = true) @PathParam ("params") String params )
119168
throws DotDataException, JSONException {
120169

121170
InitDataObject initData = webResource.init( params, request, response, false, PortletID.CONFIGURATION.toString() );
@@ -137,12 +186,28 @@ public Response getESConfigProperties ( @Context HttpServletRequest request, @Co
137186

138187
}
139188

189+
@Operation(
190+
summary = "Get license repository status",
191+
description = "Returns the current status of the license repository including total licenses and available license count."
192+
)
193+
@ApiResponses(value = {
194+
@ApiResponse(responseCode = "200",
195+
description = "License repository status retrieved successfully",
196+
content = @Content(mediaType = "application/json",
197+
schema = @Schema(implementation = ResponseEntityStringView.class))),
198+
@ApiResponse(responseCode = "401",
199+
description = "Unauthorized - backend user authentication required",
200+
content = @Content(mediaType = "application/json")),
201+
@ApiResponse(responseCode = "500",
202+
description = "Internal server error retrieving license repository status",
203+
content = @Content(mediaType = "application/json"))
204+
})
140205
@GET
141206
@Path("/licenseRepoStatus")
142207
@Produces("application/json")
143208
public Response getLicenseRepoStatus(@Context HttpServletRequest request,
144209
@Context final HttpServletResponse response,
145-
@PathParam ("params") String params) throws DotDataException, JSONException {
210+
@Parameter(description = "URL parameters for the license repository status request", required = false) @PathParam ("params") String params) throws DotDataException, JSONException {
146211
webResource.init(params, request, response,true, null);
147212

148213
JSONObject json=new JSONObject();
@@ -157,9 +222,29 @@ public Response getLicenseRepoStatus(@Context HttpServletRequest request,
157222
* @param params
158223
* @return
159224
*/
225+
@Operation(
226+
summary = "Remove server from cluster",
227+
description = "Removes a specified server from the cluster table. This operation permanently removes the server from the cluster configuration."
228+
)
229+
@ApiResponses(value = {
230+
@ApiResponse(responseCode = "200",
231+
description = "Server removed from cluster successfully (no content)"),
232+
@ApiResponse(responseCode = "401",
233+
description = "Unauthorized - backend user authentication required",
234+
content = @Content(mediaType = "application/json")),
235+
@ApiResponse(responseCode = "403",
236+
description = "Forbidden - insufficient permissions to access configuration portlet",
237+
content = @Content(mediaType = "application/json")),
238+
@ApiResponse(responseCode = "500",
239+
description = "Internal server error removing server from cluster",
240+
content = @Content(mediaType = "application/json"))
241+
})
160242
@POST
161243
@Path("/remove/{params:.*}")
162-
public Response removeFromCluster(@Context HttpServletRequest request, @Context final HttpServletResponse response, @PathParam("params") String params) {
244+
@Produces(MediaType.APPLICATION_JSON)
245+
// TODO: Consider changing to @DELETE for better REST semantics, but this would be a breaking change
246+
public Response removeFromCluster(@Context HttpServletRequest request, @Context final HttpServletResponse response,
247+
@Parameter(description = "URL parameters including serverid to remove from cluster", required = true) @PathParam("params") String params) {
163248
InitDataObject initData = webResource.init(params, request, response, true, PortletID.CONFIGURATION.toString());
164249
String serverId = initData.getParamsMap().get("serverid");
165250
try {
@@ -191,8 +276,23 @@ public Response removeFromCluster(@Context HttpServletRequest request, @Context
191276
* @param response
192277
* @return
193278
*/
279+
@Operation(
280+
summary = "Test cluster connectivity",
281+
description = "Sends a cluster ping that is recorded in the logs to test cluster connectivity and validate that all cluster nodes are communicating properly."
282+
)
283+
@ApiResponses(value = {
284+
@ApiResponse(responseCode = "200",
285+
description = "Cluster test completed successfully (no content)"),
286+
@ApiResponse(responseCode = "401",
287+
description = "Unauthorized - backend user authentication required",
288+
content = @Content(mediaType = "application/json")),
289+
@ApiResponse(responseCode = "403",
290+
description = "Forbidden - insufficient permissions to access configuration portlet",
291+
content = @Content(mediaType = "application/json"))
292+
})
194293
@GET
195294
@Path("/test")
295+
@Produces(MediaType.APPLICATION_JSON)
196296
public Response testCluster(@Context HttpServletRequest request, @Context final HttpServletResponse response) {
197297

198298

‎dotCMS/src/main/java/com/dotcms/rest/TestResource.java‎

Lines changed: 56 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
package com.dotcms.rest;
22

33
import com.dotcms.repackage.org.apache.commons.httpclient.HttpStatus;
4+
import com.dotcms.rest.annotation.SwaggerCompliant;
45
import com.dotcms.rest.config.Disabled;
56
import com.dotcms.util.xstream.XStreamHandler;
67
import com.dotmarketing.util.Logger;
@@ -23,12 +24,21 @@
2324
import javax.ws.rs.core.Context;
2425
import javax.ws.rs.core.MediaType;
2526
import javax.ws.rs.core.Response;
27+
import io.swagger.v3.oas.annotations.Operation;
28+
import io.swagger.v3.oas.annotations.Parameter;
29+
import io.swagger.v3.oas.annotations.media.Content;
30+
import io.swagger.v3.oas.annotations.media.Schema;
31+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
32+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
33+
import io.swagger.v3.oas.annotations.tags.Tag;
2634

2735
/**
2836
* @author Jonathan Gamba
2937
* Date: 8/22/13
3038
*/
39+
@SwaggerCompliant(value = "System administration and configuration APIs", batch = 4)
3140
@Disabled
41+
@Tag(name = "Testing")
3242
@Path ("/testResource")
3343
public class TestResource {
3444

@@ -49,10 +59,30 @@ public class TestResource {
4959
* @return
5060
* @throws JSONException
5161
*/
62+
@Operation(
63+
summary = "Test GET operation",
64+
description = "Example method that handles a GET operation for testing purposes. Supports JSON, XML, and JSONP response formats. This endpoint is disabled in production."
65+
)
66+
@ApiResponses(value = {
67+
@ApiResponse(responseCode = "200",
68+
description = "Test operation completed successfully",
69+
content = @Content(mediaType = "application/json",
70+
schema = @Schema(type = "object", description = "Test response containing success status, message, and echoed parameters (param1, param2)"))),
71+
@ApiResponse(responseCode = "400",
72+
description = "Bad request - missing required parameters (param1, param2)",
73+
content = @Content(mediaType = "application/json")),
74+
@ApiResponse(responseCode = "401",
75+
description = "Unauthorized - user authentication required",
76+
content = @Content(mediaType = "application/json")),
77+
@ApiResponse(responseCode = "500",
78+
description = "Internal server error during test operation",
79+
content = @Content(mediaType = "application/json"))
80+
})
5281
@GET
5382
@Path ("/testGet/{params:.*}")
5483
@Produces (MediaType.APPLICATION_JSON)
55-
public Response getDocumentCount (@Context HttpServletRequest request, @Context final HttpServletResponse response, @PathParam ("params") String params ) throws JSONException {
84+
public Response getDocumentCount (@Context HttpServletRequest request, @Context final HttpServletResponse response,
85+
@Parameter(description = "URL parameters including user/password/param1/param2 and optional type/callback", required = true) @PathParam ("params") String params ) throws JSONException {
5686

5787
InitDataObject initData = webResource.init(params, request, response, true, null);
5888

@@ -131,17 +161,37 @@ public Response getDocumentCount (@Context HttpServletRequest request, @Context
131161
* @throws IOException
132162
* @throws JSONException
133163
*/
164+
@Operation(
165+
summary = "Test POST operation",
166+
description = "Example method that handles a POST operation for testing purposes. Supports JSON, XML, and JSONP response formats. This endpoint is disabled in production."
167+
)
168+
@ApiResponses(value = {
169+
@ApiResponse(responseCode = "200",
170+
description = "Test POST operation completed successfully",
171+
content = @Content(mediaType = "application/json",
172+
schema = @Schema(type = "object", description = "Test POST response containing success status, message, and echoed parameters (param1, param2)"))),
173+
@ApiResponse(responseCode = "400",
174+
description = "Bad request - missing required parameters (param1, param2)",
175+
content = @Content(mediaType = "application/json")),
176+
@ApiResponse(responseCode = "401",
177+
description = "Unauthorized - user authentication required",
178+
content = @Content(mediaType = "application/json")),
179+
@ApiResponse(responseCode = "500",
180+
description = "Internal server error during test operation",
181+
content = @Content(mediaType = "application/json"))
182+
})
134183
@POST
135184
@Path ("/testPost")
136185
@Produces (MediaType.APPLICATION_JSON)
137186
@Consumes (MediaType.APPLICATION_FORM_URLENCODED)
138187
public Response saveTest ( @Context HttpServletRequest request,
139188
@Context final HttpServletResponse response,
140-
@FormParam ("user") String user, @FormParam ("password") String password,
141-
@FormParam ("param1") String param1,
142-
@FormParam ("param2") String param2,
143-
@FormParam ("type") String type,
144-
@FormParam ("callback") String callback ) throws IOException, JSONException {
189+
@Parameter(description = "Username for authentication", required = true) @FormParam ("user") String user,
190+
@Parameter(description = "Password for authentication", required = true) @FormParam ("password") String password,
191+
@Parameter(description = "First test parameter", required = true) @FormParam ("param1") String param1,
192+
@Parameter(description = "Second test parameter", required = true) @FormParam ("param2") String param2,
193+
@Parameter(description = "Response type (json, xml, jsonp)", required = false) @FormParam ("type") String type,
194+
@Parameter(description = "Callback function name for JSONP", required = false) @FormParam ("callback") String callback ) throws IOException, JSONException {
145195

146196
InitDataObject initData = webResource.init("user/" + user + "/password/" + password, request, response, true, null);
147197

0 commit comments

Comments
 (0)