finished REST docs. fixes #241

Graylog2 · Sep 24, 2013 · 3c61f20 · 3c61f20
1 parent 4d34802
commit 3c61f20
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 13 deletions.
diff --git a/graylog2-server/src/main/java/org/graylog2/rest/resources/system/jobs/SystemJobResource.java b/graylog2-server/src/main/java/org/graylog2/rest/resources/system/jobs/SystemJobResource.java
@@ -22,6 +22,7 @@
 import com.codahale.metrics.annotation.Timed;
 import com.google.common.collect.Lists;
 import com.google.common.collect.Maps;
+import org.graylog2.rest.documentation.annotations.*;
 import org.graylog2.rest.resources.RestResource;
 import org.graylog2.rest.resources.system.jobs.requests.TriggerRequest;
 import org.graylog2.system.jobs.NoSuchJobException;
@@ -41,12 +42,14 @@
 /**
  * @author Lennart Koopmann <lennart@torch.sh>
  */
+@Api(value = "System/Jobs", description = "Systemjobs")
 @Path("/system/jobs")
 public class SystemJobResource extends RestResource {
 
     private static final Logger LOG = LoggerFactory.getLogger(SystemJobResource.class);
 
     @GET @Timed
+    @ApiOperation(value = "List currently running jobs")
     @Produces(MediaType.APPLICATION_JSON)
     public String list() {
         List<Map<String, Object>> jobs = Lists.newArrayList();
@@ -63,8 +66,12 @@ public String list() {
 
     @GET @Timed
     @Path("/{jobId}")
+    @ApiOperation(value = "Get information of a specific currently running job")
     @Produces(MediaType.APPLICATION_JSON)
-    public String get(@PathParam("jobId") String jobId) {
+    @ApiResponses(value = {
+            @ApiResponse(code = 404, message = "Job not found.")
+    })
+    public String get(@ApiParam(title = "jobId", required = true) @PathParam("jobId") String jobId) {
         if (jobId == null || jobId.isEmpty()) {
             LOG.error("Missing jobId. Returning HTTP 400.");
             throw new WebApplicationException(400);
@@ -81,9 +88,15 @@ public String get(@PathParam("jobId") String jobId) {
     }
 
     @POST @Timed
+    @ApiOperation(value = "Trigger new job")
     @Consumes(MediaType.APPLICATION_JSON)
     @Produces(MediaType.APPLICATION_JSON)
-    public Response trigger(String body) {
+    @ApiResponses(value = {
+            @ApiResponse(code = 202, message = "Job accepted."),
+            @ApiResponse(code = 400, message = "There is no such systemjob type."),
+            @ApiResponse(code = 403, message = "Maximum concurrency level of this systemjob type reached.")
+    })
+    public Response trigger(@ApiParam(title = "JSON body", required = true) String body) {
         if (body == null || body.isEmpty()) {
             LOG.error("Missing parameters. Returning HTTP 400.");
             throw new WebApplicationException(400);
@@ -108,7 +121,7 @@ public Response trigger(String body) {
         try {
             core.getSystemJobManager().submit(job);
         } catch (SystemJobConcurrencyException e) {
-            LOG.error("Concurrency level of this job reached: " + e.getMessage());
+            LOG.error("Maximum concurrency level of this job reached. ", e);
             throw new WebApplicationException(403);
         }
 

diff --git a/graylog2-server/src/main/java/org/graylog2/rest/resources/system/logs/LoggersResource.java b/graylog2-server/src/main/java/org/graylog2/rest/resources/system/logs/LoggersResource.java
@@ -23,6 +23,7 @@
 import com.google.common.collect.Maps;
 import org.apache.log4j.Level;
 import org.apache.log4j.Logger;
+import org.graylog2.rest.documentation.annotations.*;
 import org.graylog2.rest.resources.RestResource;
 import org.slf4j.LoggerFactory;
 
@@ -34,6 +35,7 @@
 /**
  * @author Lennart Koopmann <lennart@torch.sh>
  */
+@Api(value = "System/Loggers", description = "Internal Graylog2 loggers")
 @Path("/system/loggers")
 public class LoggersResource extends RestResource {
 
@@ -46,8 +48,8 @@ public class LoggersResource extends RestResource {
         put("sockets", new Subsystem("Sockets", "netty", "All messages related to socket communication."));
     }};
 
-    @GET
-    @Timed
+    @GET @Timed
+    @ApiOperation(value = "List all loggers and their current levels")
     @Produces(MediaType.APPLICATION_JSON)
     public String loggers() {
         Map<String, Object> loggerList = Maps.newHashMap();
@@ -70,9 +72,9 @@ public String loggers() {
         return json(result);
     }
 
-    @GET
-    @Timed
+    @GET @Timed
     @Path("/subsystems")
+    @ApiOperation(value = "List all logger subsystems")
     @Produces(MediaType.APPLICATION_JSON)
     public String subsytems() {
         Map<String, Object> result = Maps.newHashMap();
@@ -89,10 +91,16 @@ public String subsytems() {
         return json(result);
     }
 
-    @PUT
+    @PUT @Timed
+    @ApiOperation(value = "Set the loglevel of a whole subsystem",
+                  notes = "Provided level is falling back to DEBUG if it does not exist")
+    @ApiResponses(value = {
+            @ApiResponse(code = 404, message = "No such subsystem.")
+    })
     @Path("/subsystems/{subsystem}/level/{level}")
-    @Timed
-    public Response setSubsystemLoggerLevel(@PathParam("subsystem") String subsystemTitle, @PathParam("level") String level) {
+    public Response setSubsystemLoggerLevel(
+            @ApiParam(title = "subsystem", required = true) @PathParam("subsystem") String subsystemTitle,
+            @ApiParam(title = "level", required = true) @PathParam("level") String level) {
         if (!SUBSYSTEMS.containsKey(subsystemTitle)) {
             LOG.warn("No such subsystem: [{}]. Returning 404.", subsystemTitle);
             return Response.status(404).build();
@@ -110,10 +118,13 @@ public Response setSubsystemLoggerLevel(@PathParam("subsystem") String subsystem
         return Response.ok().build();
     }
 
-    @PUT
+    @PUT @Timed
+    @ApiOperation(value = "Set the loglevel of a single logger",
+            notes = "Provided level is falling back to DEBUG if it does not exist")
     @Path("/{loggerName}/level/{level}")
-    @Timed
-    public Response setSingleLoggerLevel(@PathParam("loggerName") String loggerName, @PathParam("level") String level) {
+    public Response setSingleLoggerLevel(
+            @ApiParam(title = "loggerName", required = true) @PathParam("loggerName") String loggerName,
+            @ApiParam(title = "level", required = true) @PathParam("level") String level) {
         // This is never null. Worst case is a logger that does not exist.
         Logger logger = Logger.getLogger(loggerName);