#326 use Swagger UI to display API

vipshop · Jan 4, 2018 · 88642cd · 88642cd
1 parent 3696648
commit 88642cd
Show file tree

Hide file tree

Showing 12 changed files with 148 additions and 18 deletions.
diff --git a/pom.xml b/pom.xml
@@ -78,6 +78,8 @@
 		<javaee-web-api.version>7.0</javaee-web-api.version>
 		<javax.servlet-api.version>3.1.0</javax.servlet-api.version>
 
+		<swagger.version>2.4.0</swagger.version>
+
 		<junit.version>4.12</junit.version>
 		<assertj.version>1.7.1</assertj.version>
 		<unitils.core.version>3.4.2</unitils.core.version>
@@ -372,6 +374,21 @@
 			</dependency>
 			<!-- DB end -->
 
+			<!-- Swagger begin -->
+			<dependency>
+				<groupId>io.springfox</groupId>
+				<artifactId>springfox-swagger2</artifactId>
+				<version>${swagger.version}</version>
+			</dependency>
+
+			<dependency>
+				<groupId>io.springfox</groupId>
+				<artifactId>springfox-swagger-ui</artifactId>
+				<version>${swagger.version}</version>
+			</dependency>
+			<!-- Swagger end -->
+
+
 			<!-- Test begin -->
 			<dependency>
 				<groupId>junit</groupId>

diff --git a/saturn-console-api/pom.xml b/saturn-console-api/pom.xml
@@ -217,6 +217,13 @@
 		</dependency>
 		<!-- Http Client End -->
 
+		<!-- Swagger Begin -->
+		<dependency>
+			<groupId>io.springfox</groupId>
+			<artifactId>springfox-swagger2</artifactId>
+		</dependency>
+		<!-- Swagger End -->
+
 		<!-- Test Begin -->
 		<dependency>
 			<groupId>javax.servlet</groupId>

diff --git a/...e-api/src/main/java/com/vip/saturn/job/console/controller/DisableSwaggerUIController.java b/...e-api/src/main/java/com/vip/saturn/job/console/controller/DisableSwaggerUIController.java
@@ -0,0 +1,22 @@
+package com.vip.saturn.job.console.controller;
+
+import javax.servlet.http.HttpServletResponse;
+import org.springframework.context.annotation.Profile;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.GetMapping;
+
+/**
+ * Display swagger-ui.html in production.
+ *
+ * @author kfchu
+ */
+@Profile("!dev")
+@Controller
+public class DisableSwaggerUIController {
+
+	@GetMapping(value = "swagger-ui.html")
+	public void getSwagger(HttpServletResponse httpResponse) {
+		httpResponse.setStatus(HttpStatus.NOT_FOUND.value());
+	}
+}
diff --git a/...i/src/main/java/com/vip/saturn/job/console/controller/gui/ExecutorOverviewController.java b/...i/src/main/java/com/vip/saturn/job/console/controller/gui/ExecutorOverviewController.java
@@ -4,11 +4,14 @@
 import com.vip.saturn.job.console.aop.annotation.Audit;
 import com.vip.saturn.job.console.aop.annotation.AuditParam;
 import com.vip.saturn.job.console.controller.SuccessResponseEntity;
+import com.vip.saturn.job.console.domain.RequestResult;
 import com.vip.saturn.job.console.domain.ServerBriefInfo;
 import com.vip.saturn.job.console.domain.ServerStatus;
 import com.vip.saturn.job.console.exception.SaturnJobConsoleException;
 import com.vip.saturn.job.console.exception.SaturnJobConsoleGUIException;
 import com.vip.saturn.job.console.service.ExecutorService;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import java.util.List;
 import javax.annotation.Resource;
 import javax.servlet.http.HttpServletRequest;
@@ -23,7 +26,7 @@
 import org.springframework.web.bind.annotation.RequestParam;
 
 /**
- * Executor overview page controller.
+ * Executor overview related operations.
  *
  * @author kfchu
  */
@@ -41,6 +44,7 @@ public class ExecutorOverviewController extends AbstractGUIController {
 	/**
 	 * 获取域下所有executor基本信息
 	 */
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@GetMapping
 	public SuccessResponseEntity getExecutors(final HttpServletRequest request,
 			@PathVariable String namespace, @RequestParam(required = false) String status)
@@ -55,6 +59,7 @@ public SuccessResponseEntity getExecutors(final HttpServletRequest request,
 	/**
 	 * 获取executor被分配的作业分片信息
 	 */
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@GetMapping(value = "/{executorName}/allocation")
 	public SuccessResponseEntity getExecutorAllocation(final HttpServletRequest request,
 			@PathVariable String namespace, @PathVariable String executorName) throws SaturnJobConsoleException {
@@ -64,6 +69,7 @@ public SuccessResponseEntity getExecutorAllocation(final HttpServletRequest requ
 	/**
 	 * 一键重排
 	 */
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@Audit
 	@PostMapping(value = "/shardAll")
 	public SuccessResponseEntity shardAll(final HttpServletRequest request,
@@ -76,6 +82,7 @@ public SuccessResponseEntity shardAll(final HttpServletRequest request,
 	/*
 	 *	摘流量与流量恢复，其中executor必须online
 	 */
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@Audit
 	@PostMapping(value = "/{executorName}/traffic")
 	public SuccessResponseEntity extractOrRecoverTraffic(final HttpServletRequest request,
@@ -93,6 +100,7 @@ public SuccessResponseEntity extractOrRecoverTraffic(final HttpServletRequest re
 	/*
 	 *	批量摘流量与流量恢复，其中executor必须online
 	 */
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@Audit
 	@PostMapping(value = "/traffic")
 	public SuccessResponseEntity batchExtractOrRecoverTraffic(final HttpServletRequest request,
@@ -138,6 +146,7 @@ private void extractOrRecoverTraffic(String namespace, String executorName, Stri
 	/**
 	 * 移除executor
 	 */
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@Audit
 	@DeleteMapping(value = "/{executorName}")
 	public SuccessResponseEntity removeExecutor(final HttpServletRequest request,
@@ -153,6 +162,7 @@ public SuccessResponseEntity removeExecutor(final HttpServletRequest request,
 	/**
 	 * 批量移除executor
 	 */
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@Audit
 	@DeleteMapping
 	public SuccessResponseEntity batchRemoveExecutors(final HttpServletRequest request,
@@ -195,6 +205,7 @@ private void checkExecutorStatus(String namespace, String executorName, ServerSt
 	/**
 	 * 一键Dump，包括threadump和gc.log。
 	 */
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@Audit
 	@PostMapping(value = "/{executorName}/dump")
 	public SuccessResponseEntity dump(final HttpServletRequest request,

diff --git a/...n-console-api/src/main/java/com/vip/saturn/job/console/controller/gui/HomeController.java b/...n-console-api/src/main/java/com/vip/saturn/job/console/controller/gui/HomeController.java
@@ -5,6 +5,8 @@
 import com.vip.saturn.job.console.domain.RequestResult;
 import com.vip.saturn.job.console.exception.SaturnJobConsoleException;
 import com.vip.saturn.job.console.exception.SaturnJobConsoleGUIException;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.stereotype.Controller;
@@ -18,14 +20,15 @@
 import java.util.List;
 
 /**
- * Home page controller.
+ * Name space related operations.
  *
  * @author hebelala
  */
 @Controller
 @RequestMapping("/console/namespaces")
 public class HomeController extends AbstractGUIController {
 
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@GetMapping
 	public SuccessResponseEntity getNamespaces(final HttpServletRequest request)
 			throws SaturnJobConsoleException {
@@ -37,6 +40,7 @@ public SuccessResponseEntity getNamespaces(final HttpServletRequest request)
 		return new SuccessResponseEntity(namespaceList);
 	}
 
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@GetMapping(value = "/{namespace:.+}")
 	public SuccessResponseEntity getNamespace(final HttpServletRequest request, @PathVariable String namespace)
 			throws SaturnJobConsoleException {

diff --git a/...sole-api/src/main/java/com/vip/saturn/job/console/controller/gui/JobConfigController.java b/...sole-api/src/main/java/com/vip/saturn/job/console/controller/gui/JobConfigController.java
@@ -5,8 +5,11 @@
 import com.vip.saturn.job.console.aop.annotation.AuditType;
 import com.vip.saturn.job.console.controller.SuccessResponseEntity;
 import com.vip.saturn.job.console.domain.JobConfig;
+import com.vip.saturn.job.console.domain.RequestResult;
 import com.vip.saturn.job.console.exception.SaturnJobConsoleException;
 import com.vip.saturn.job.console.service.JobService;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -18,6 +21,8 @@
 import javax.servlet.http.HttpServletRequest;
 
 /**
+ * Job config related operations.
+ *
  * @author hebelala
  */
 @Controller
@@ -27,14 +32,16 @@ public class JobConfigController extends AbstractGUIController {
 	@Resource
 	private JobService jobService;
 
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@GetMapping
 	public SuccessResponseEntity getJobConfig(final HttpServletRequest request,
 			@AuditParam("namespace") @PathVariable String namespace,
 			@AuditParam("jobName") @PathVariable String jobName) throws SaturnJobConsoleException {
 		return new SuccessResponseEntity(jobService.getJobConfigVo(namespace, jobName));
 	}
 
-	@Audit(type = AuditType.WEB)
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
+	@Audit
 	@PostMapping
 	public SuccessResponseEntity updateJobConfig(final HttpServletRequest request,
 			@AuditParam("namespace") @PathVariable String namespace,

diff --git a/...e-api/src/main/java/com/vip/saturn/job/console/controller/gui/JobExecutionController.java b/...e-api/src/main/java/com/vip/saturn/job/console/controller/gui/JobExecutionController.java
@@ -1,8 +1,11 @@
 package com.vip.saturn.job.console.controller.gui;
 
 import com.vip.saturn.job.console.controller.SuccessResponseEntity;
+import com.vip.saturn.job.console.domain.RequestResult;
 import com.vip.saturn.job.console.exception.SaturnJobConsoleException;
 import com.vip.saturn.job.console.service.JobService;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import javax.annotation.Resource;
 import javax.servlet.http.HttpServletRequest;
 import org.springframework.stereotype.Controller;
@@ -26,12 +29,14 @@ public class JobExecutionController extends AbstractGUIController {
 	/**
 	 * 获取作业执行状态
 	 */
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@GetMapping(value = "/status")
 	public SuccessResponseEntity getExecutionStatus(final HttpServletRequest request, @PathVariable String namespace,
 			@PathVariable String jobName) throws SaturnJobConsoleException {
 		return new SuccessResponseEntity(jobService.getExecutionStatus(namespace, jobName));
 	}
 
+	@ApiResponses(value = {@ApiResponse(code = 200, message = "Success/Fail", response = RequestResult.class)})
 	@GetMapping(value = "/log")
 	public SuccessResponseEntity getExecutionLog(final HttpServletRequest request, @PathVariable String namespace,
 			@PathVariable String jobName, @RequestParam String jobItem) throws SaturnJobConsoleException {