From ffa5816042b90d079101be41e7ba2bd5c5a1ea0c Mon Sep 17 00:00:00 2001
From: Muluo-cyan <1217593253@qq.com>
Date: Tue, 15 Oct 2024 23:48:09 +0800
Subject: [PATCH] feature: support swagger

---
 console/pom.xml                                     | 13 +++++++++++++
 .../seata/console/controller/AuthController.java    |  4 ++++
 .../console/controller/OverviewController.java      |  4 ++++
 .../seata/server/auth/config/Swagger2Config.java    |  7 +++++++
 .../auth/controller/ClusterAuthController.java      |  6 ++++++
 .../console/controller/BranchSessionController.java |  2 ++
 .../console/controller/GlobalLockController.java    |  4 ++++
 .../console/controller/GlobalSessionController.java |  4 ++++
 .../seata/server/controller/ClusterController.java  |  6 ++++++
 .../seata/server/controller/HealthController.java   |  4 ++++
 .../server/controller/VGroupMappingController.java  |  5 +++++
 11 files changed, 59 insertions(+)

diff --git a/console/pom.xml b/console/pom.xml
index 16fba6a55ee..7e168de9502 100644
--- a/console/pom.xml
+++ b/console/pom.xml
@@ -142,6 +142,19 @@
             <groupId>javax.servlet</groupId>
             <artifactId>javax.servlet-api</artifactId>
         </dependency>
+
+        <!-- swagger -->
+        <dependency>
+            <groupId>io.springfox</groupId>
+            <artifactId>springfox-swagger2</artifactId>
+            <version>2.7.0</version>
+        </dependency>
+        <dependency>
+            <groupId>io.springfox</groupId>
+            <artifactId>springfox-swagger-ui</artifactId>
+            <version>2.7.0</version>
+        </dependency>
+
         <!--<dependency>
             <groupId>io.jsonwebtoken</groupId>
             <artifactId>jjwt</artifactId>
diff --git a/console/src/main/java/org/apache/seata/console/controller/AuthController.java b/console/src/main/java/org/apache/seata/console/controller/AuthController.java
index c4683818619..b66f4ad17ee 100644
--- a/console/src/main/java/org/apache/seata/console/controller/AuthController.java
+++ b/console/src/main/java/org/apache/seata/console/controller/AuthController.java
@@ -16,6 +16,8 @@
  */
 package org.apache.seata.console.controller;
 
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.apache.seata.common.result.Code;
 import org.apache.seata.common.result.SingleResult;
 import org.apache.seata.console.config.ConsoleSecurityConfig;
@@ -39,6 +41,7 @@
  *
  */
 @RestController
+@Api(tags = "Console authentication APIs")
 @RequestMapping("/api/v1/auth")
 public class AuthController {
     @Autowired
@@ -57,6 +60,7 @@ public class AuthController {
      * @return HTTP code equal to 200 indicates that Seata is in right states. HTTP code equal to 500 indicates that
      * Seata is in broken states.
      */
+    @ApiOperation("login and get access token and refresh token")
     @PostMapping("/login")
     public SingleResult<String> login(HttpServletResponse response, @RequestBody User user) {
         UsernamePasswordAuthenticationToken authenticationToken = new UsernamePasswordAuthenticationToken(
diff --git a/console/src/main/java/org/apache/seata/console/controller/OverviewController.java b/console/src/main/java/org/apache/seata/console/controller/OverviewController.java
index 48a4e4aece9..2045d037f09 100644
--- a/console/src/main/java/org/apache/seata/console/controller/OverviewController.java
+++ b/console/src/main/java/org/apache/seata/console/controller/OverviewController.java
@@ -16,6 +16,8 @@
  */
 package org.apache.seata.console.controller;
 
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.apache.seata.common.result.Code;
 import org.apache.seata.common.result.SingleResult;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -31,6 +33,7 @@
  *
  */
 @RestController
+@Api(tags = "Overview APIs")
 @RequestMapping("/api/v1/overview")
 public class OverviewController {
 
@@ -39,6 +42,7 @@ public class OverviewController {
      *
      * @return the data
      */
+    @ApiOperation("get data")
     @GetMapping(value = "/getData")
     public SingleResult<List> getData() {
         List<Map<String, Object>> result = new ArrayList<>();
diff --git a/server/src/main/java/org/apache/seata/server/auth/config/Swagger2Config.java b/server/src/main/java/org/apache/seata/server/auth/config/Swagger2Config.java
index 3fc337bbb16..3afdc45a0b8 100644
--- a/server/src/main/java/org/apache/seata/server/auth/config/Swagger2Config.java
+++ b/server/src/main/java/org/apache/seata/server/auth/config/Swagger2Config.java
@@ -1,3 +1,4 @@
+<<<<<<< HEAD
 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
@@ -17,6 +18,12 @@
 package org.apache.seata.server.auth.config;
 
 import com.google.common.base.Predicates;
+=======
+package org.apache.seata.server.auth.config;
+
+import com.google.common.base.Predicates;
+import org.apache.seata.console.config.ConsoleSecurityConfig;
+>>>>>>> dcbba42f0 (feature: support swagger)
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.servlet.config.annotation.EnableWebMvc;
diff --git a/server/src/main/java/org/apache/seata/server/auth/controller/ClusterAuthController.java b/server/src/main/java/org/apache/seata/server/auth/controller/ClusterAuthController.java
index 68e444658ec..21344a72084 100644
--- a/server/src/main/java/org/apache/seata/server/auth/controller/ClusterAuthController.java
+++ b/server/src/main/java/org/apache/seata/server/auth/controller/ClusterAuthController.java
@@ -16,6 +16,8 @@
  */
 package org.apache.seata.server.auth.controller;
 
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.apache.seata.common.result.Code;
 import org.apache.seata.common.result.SingleResult;
 import org.apache.seata.server.auth.config.ClusterSecurityConfig;
@@ -36,11 +38,14 @@
 import javax.servlet.http.HttpServletResponse;
 
 @RestController
+@Api(tags = "Cluster authentication APIs")
 @RequestMapping("/metadata/v1/auth")
 public class ClusterAuthController {
+
     @Autowired
     @Qualifier("clusterJwtTokenUtils")
     private ClusterJwtTokenUtils jwtTokenUtils;
+
     @Autowired
     @Qualifier("clusterAuthenticationManager")
     private AuthenticationManager authenticationManager;
@@ -53,6 +58,7 @@ public class ClusterAuthController {
      * @return HTTP code equal to 200 indicates that Seata is in right states. HTTP code equal to 500 indicates that
      * Seata is in broken states.
      */
+    @ApiOperation("login to get access token and refresh token")
     @PostMapping("/login")
     public SingleResult<String> login(HttpServletResponse response, @RequestBody User user) {
         UsernamePasswordAuthenticationToken authenticationToken = new UsernamePasswordAuthenticationToken(
diff --git a/server/src/main/java/org/apache/seata/server/console/controller/BranchSessionController.java b/server/src/main/java/org/apache/seata/server/console/controller/BranchSessionController.java
index a1e07eae3ac..43c61d0cf1b 100644
--- a/server/src/main/java/org/apache/seata/server/console/controller/BranchSessionController.java
+++ b/server/src/main/java/org/apache/seata/server/console/controller/BranchSessionController.java
@@ -16,6 +16,7 @@
  */
 package org.apache.seata.server.console.controller;
 
+import io.swagger.annotations.Api;
 import org.apache.seata.server.console.service.BranchSessionService;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
@@ -26,6 +27,7 @@
  * Branch Session Controller
  */
 @RestController
+@Api(tags = "Branch session APIs")
 @RequestMapping("/api/v1/console/branchSession")
 public class BranchSessionController {
 
diff --git a/server/src/main/java/org/apache/seata/server/console/controller/GlobalLockController.java b/server/src/main/java/org/apache/seata/server/console/controller/GlobalLockController.java
index 95d7cabf55c..452a8c4e5d3 100644
--- a/server/src/main/java/org/apache/seata/server/console/controller/GlobalLockController.java
+++ b/server/src/main/java/org/apache/seata/server/console/controller/GlobalLockController.java
@@ -18,6 +18,8 @@
 
 import javax.annotation.Resource;
 
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.apache.seata.common.result.PageResult;
 import org.apache.seata.server.console.param.GlobalLockParam;
 import org.apache.seata.server.console.vo.GlobalLockVO;
@@ -32,6 +34,7 @@
  * Global Lock Controller
  */
 @RestController
+@Api(tags = "Global lock APIs")
 @RequestMapping("/api/v1/console/globalLock")
 public class GlobalLockController {
 
@@ -43,6 +46,7 @@ public class GlobalLockController {
      * @param param the param
      * @return the list of GlobalLockVO
      */
+    @ApiOperation("query global lock")
     @GetMapping("query")
     public PageResult<GlobalLockVO> query(@ModelAttribute GlobalLockParam param) {
         return globalLockService.query(param);
diff --git a/server/src/main/java/org/apache/seata/server/console/controller/GlobalSessionController.java b/server/src/main/java/org/apache/seata/server/console/controller/GlobalSessionController.java
index aa039a663b6..91e47e6c738 100644
--- a/server/src/main/java/org/apache/seata/server/console/controller/GlobalSessionController.java
+++ b/server/src/main/java/org/apache/seata/server/console/controller/GlobalSessionController.java
@@ -18,6 +18,8 @@
 
 import javax.annotation.Resource;
 
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.apache.seata.server.console.param.GlobalSessionParam;
 import org.apache.seata.common.result.PageResult;
 import org.apache.seata.server.console.vo.GlobalSessionVO;
@@ -31,6 +33,7 @@
  * Global Session Controller
  */
 @RestController
+@Api(tags = "Global session APIs")
 @RequestMapping("/api/v1/console/globalSession")
 public class GlobalSessionController {
 
@@ -42,6 +45,7 @@ public class GlobalSessionController {
      * @param param param for query globalSession
      * @return  the list of GlobalSessionVO
      */
+    @ApiOperation("query global session")
     @GetMapping("query")
     public PageResult<GlobalSessionVO> query(@ModelAttribute GlobalSessionParam param) {
         return globalSessionService.query(param);
diff --git a/server/src/main/java/org/apache/seata/server/controller/ClusterController.java b/server/src/main/java/org/apache/seata/server/controller/ClusterController.java
index 816f6e3e250..3052a5880dc 100644
--- a/server/src/main/java/org/apache/seata/server/controller/ClusterController.java
+++ b/server/src/main/java/org/apache/seata/server/controller/ClusterController.java
@@ -28,6 +28,8 @@
 import com.alipay.sofa.jraft.RouteTable;
 import com.alipay.sofa.jraft.conf.Configuration;
 import com.alipay.sofa.jraft.entity.PeerId;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.apache.seata.common.ConfigurationKeys;
 import org.apache.seata.common.metadata.MetadataResponse;
 import org.apache.seata.common.metadata.Node;
@@ -55,6 +57,7 @@
 /**
  */
 @RestController
+@Api(tags = "Raft cluster APIs")
 @RequestMapping("/metadata/v1")
 public class ClusterController {
 
@@ -73,6 +76,7 @@ private void init() {
         this.serverProperties = applicationContext.getBean(ServerProperties.class);
     }
 
+    @ApiOperation("changeCluster")
     @PostMapping("/changeCluster")
     public Result<?> changeCluster(@RequestParam String raftClusterStr) {
         Result<?> result = new Result<>();
@@ -89,6 +93,7 @@ public Result<?> changeCluster(@RequestParam String raftClusterStr) {
         return result;
     }
 
+    @ApiOperation("cluster")
     @GetMapping("/cluster")
     public MetadataResponse cluster(String group) {
         MetadataResponse metadataResponse = new MetadataResponse();
@@ -122,6 +127,7 @@ public MetadataResponse cluster(String group) {
         return metadataResponse;
     }
 
+    @ApiOperation("watch follower")
     @PostMapping("/watch")
     public void watch(HttpServletRequest request, @RequestParam Map<String, Object> groupTerms,
         @RequestParam(defaultValue = "28000") int timeout) {
diff --git a/server/src/main/java/org/apache/seata/server/controller/HealthController.java b/server/src/main/java/org/apache/seata/server/controller/HealthController.java
index a5193402776..0637722afa6 100644
--- a/server/src/main/java/org/apache/seata/server/controller/HealthController.java
+++ b/server/src/main/java/org/apache/seata/server/controller/HealthController.java
@@ -16,6 +16,8 @@
  */
 package org.apache.seata.server.controller;
 
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.apache.seata.server.ServerRunner;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -24,6 +26,7 @@
 /**
  */
 @RestController
+@Api(tags = "Health APIs")
 public class HealthController {
 
     private static final String OK = "ok";
@@ -34,6 +37,7 @@ public class HealthController {
 
 
     @RequestMapping("/health")
+    @ApiOperation("health")
     String healthCheck() {
         return serverRunner.started() ? OK : NOT_OK;
     }
diff --git a/server/src/main/java/org/apache/seata/server/controller/VGroupMappingController.java b/server/src/main/java/org/apache/seata/server/controller/VGroupMappingController.java
index 348a7502830..81ab882c334 100644
--- a/server/src/main/java/org/apache/seata/server/controller/VGroupMappingController.java
+++ b/server/src/main/java/org/apache/seata/server/controller/VGroupMappingController.java
@@ -16,6 +16,8 @@
  */
 package org.apache.seata.server.controller;
 
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
 import org.apache.seata.common.metadata.namingserver.Instance;
 import org.apache.seata.common.result.Result;
 import org.apache.seata.common.util.StringUtils;
@@ -37,6 +39,7 @@
 import static org.apache.seata.common.ConfigurationKeys.NAMING_SERVER;
 
 @RestController
+@Api(tags = "VGroup mapping APIs")
 @RequestMapping("/vgroup/v1")
 public class VGroupMappingController {
 
@@ -59,6 +62,7 @@ private void init() {
      * @param vGroup
      * @return
      */
+    @ApiOperation("add VGroup")
     @GetMapping("/addVGroup")
     public Result<?> addVGroup(@RequestParam String vGroup, @RequestParam String unit) {
         Result<?> result = new Result<>();
@@ -82,6 +86,7 @@ public Result<?> addVGroup(@RequestParam String vGroup, @RequestParam String uni
      * @param vGroup
      * @return
      */
+    @ApiOperation("remove VGroup")
     @GetMapping("/removeVGroup")
     public Result<?> removeVGroup(@RequestParam String vGroup) {
         Result<?> result = new Result<>();