增加权限相关文档说明

jetlinks-manager/authentication-manager/src/main/java/org/jetlinks/community/auth/captcha/CaptchaController.java

@@ -2,6 +2,10 @@ package org.jetlinks.community.auth.captcha;
 
 import com.wf.captcha.SpecCaptcha;
 import com.wf.captcha.base.Captcha;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.AllArgsConstructor;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -23,6 +27,7 @@ import java.util.UUID;
 @Authorize(ignore = true)
 @AllArgsConstructor
 @RequestMapping("/authorize/captcha")
+@Tag(name = "验证码接口")
 public class CaptchaController {
 
     private final CaptchaProperties properties;
@@ -30,20 +35,24 @@ public class CaptchaController {
     private final ReactiveRedisOperations<String, String> redis;
 
     @GetMapping("/config")
-    public Mono<CaptchaConfig> getCaptcha() {
-        CaptchaConfig captchaConfig=new CaptchaConfig();
+    @Operation(summary = "获取验证码相关配置信息")
+    public Mono<CaptchaConfig> createCaptcha() {
+        CaptchaConfig captchaConfig = new CaptchaConfig();
         captchaConfig.setEnabled(properties.isEnabled());
         captchaConfig.setType(properties.getType().name());
         return Mono.just(captchaConfig);
     }
 
     @GetMapping("/image")
-    public Mono<CaptchaInfo> createCaptcha(@RequestParam(defaultValue = "130") int width,
-                                           @RequestParam(defaultValue = "40") int height) {
+    @Operation(summary = "获取验证码图片")
+    public Mono<CaptchaInfo> createCaptcha(@RequestParam(defaultValue = "130")
+                                           @Parameter(description = "宽度,默认130px") int width,
+                                           @RequestParam(defaultValue = "40")
+                                           @Parameter(description = "高度,默认40px") int height) {
         if (!properties.isEnabled()) {
             return Mono.empty();
         }
-        SpecCaptcha captcha = new SpecCaptcha(width, height, 5);
+        SpecCaptcha captcha = new SpecCaptcha(width, height, 4);
         captcha.setCharType(Captcha.TYPE_DEFAULT);
 
         String base64 = captcha.toBase64();
@@ -82,8 +91,10 @@ public class CaptchaController {
     @AllArgsConstructor
     @NoArgsConstructor
     public static class CaptchaInfo {
+        @Schema(description = "验证码标识,登录时需要在参数[verifyKey]传入此值.")
         private String key;
 
+        @Schema(description = "图片Base64,以data:image/png;base64,开头")
         private String base64;
     }
 
@@ -91,9 +102,11 @@ public class CaptchaController {
     @Setter
     @AllArgsConstructor
     @NoArgsConstructor
-    public static class CaptchaConfig{
+    public static class CaptchaConfig {
+        @Schema(description = "是否开启验证码")
         private boolean enabled;
 
+        @Schema(description = "验证码类型")
         private String type;
     }
 }

jetlinks-manager/authentication-manager/src/main/java/org/jetlinks/community/auth/service/AuthorizationSettingDetailService.java

@@ -0,0 +1,58 @@
+package org.jetlinks.community.auth.service;
+
+import lombok.AllArgsConstructor;
+import org.hswebframework.web.authorization.DimensionProvider;
+import org.hswebframework.web.system.authorization.api.entity.AuthorizationSettingEntity;
+import org.hswebframework.web.system.authorization.defaults.service.DefaultAuthorizationSettingService;
+import org.jetlinks.community.auth.web.request.AuthorizationSettingDetail;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+
+import java.util.List;
+
+@Component
+@AllArgsConstructor
+public class AuthorizationSettingDetailService {
+
+    private final DefaultAuthorizationSettingService settingService;
+    private final List<DimensionProvider> providers;
+
+    @Transactional
+    public Mono<Void> saveDetail(Flux<AuthorizationSettingDetail> detailFlux) {
+        return detailFlux
+            //先删除旧的权限设置
+            .flatMap(detail -> settingService.getRepository().createDelete()
+                .where(AuthorizationSettingEntity::getDimensionType, detail.getTargetType())
+                .and(AuthorizationSettingEntity::getDimensionTarget, detail.getTargetId())
+                .execute()
+                .thenReturn(detail))
+            .flatMap(detail ->
+                Flux.fromIterable(providers)
+                    .flatMap(provider -> provider
+                        .getAllType()
+                        .filter(type -> type.getId().equals(detail.getTargetType()))
+                        .singleOrEmpty()
+                        .flatMap(type -> provider.getDimensionById(type, detail.getTargetId()))
+                        .flatMapIterable(detail::toEntity))
+                    .switchIfEmpty(Flux.defer(() -> Flux.fromIterable(detail.toEntity())))
+                    .distinct(AuthorizationSettingEntity::getPermission)
+            )
+            .as(settingService::save)
+            .then();
+    }
+
+    public Mono<AuthorizationSettingDetail> getSettingDetail(String targetType,
+                                                             String target) {
+        return settingService
+            .createQuery()
+            .where(AuthorizationSettingEntity::getDimensionTarget, target)
+            .and(AuthorizationSettingEntity::getDimensionType, targetType)
+            .fetch()
+            .collectList()
+            .map(AuthorizationSettingDetail::fromEntity)
+            ;
+    }
+
+}

jetlinks-manager/authentication-manager/src/main/java/org/jetlinks/community/auth/web/AuthorizationSettingDetailController.java

@@ -1,74 +1,50 @@
 package org.jetlinks.community.auth.web;
 
-import org.hswebframework.web.authorization.DimensionProvider;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.AllArgsConstructor;
 import org.hswebframework.web.authorization.annotation.Authorize;
 import org.hswebframework.web.authorization.annotation.Resource;
 import org.hswebframework.web.authorization.annotation.SaveAction;
-import org.hswebframework.web.system.authorization.api.entity.AuthorizationSettingEntity;
-import org.hswebframework.web.system.authorization.defaults.service.DefaultAuthorizationSettingService;
+import org.jetlinks.community.auth.service.AuthorizationSettingDetailService;
 import org.jetlinks.community.auth.web.request.AuthorizationSettingDetail;
 import org.springframework.web.bind.annotation.*;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
-import java.util.List;
-
 @RestController
 @RequestMapping("/autz-setting/detail")
 @Authorize
 @Resource(
     id = "autz-setting",
     name = "权限分配",
-    group = {"system"}
+    group = "system"
 )
+@AllArgsConstructor
+@Tag(name = "权限分配")
 public class AuthorizationSettingDetailController {
 
-    private final DefaultAuthorizationSettingService settingService;
-
-    private final List<DimensionProvider> providers;
-
-    public AuthorizationSettingDetailController(DefaultAuthorizationSettingService settingService, List<DimensionProvider> providers) {
-        this.settingService = settingService;
-        this.providers = providers;
-    }
+    private final AuthorizationSettingDetailService settingService;
 
     @PostMapping("/_save")
     @SaveAction
+    @Operation(summary = "赋权")
     public Mono<Boolean> saveSettings(@RequestBody Flux<AuthorizationSettingDetail> detailFlux) {
-        return detailFlux
-            //先删除旧的权限设置
-            .flatMap(detail -> settingService.getRepository().createDelete()
-                .where(AuthorizationSettingEntity::getDimensionType, detail.getTargetType())
-                .and(AuthorizationSettingEntity::getDimensionTarget, detail.getTargetId())
-                .execute()
-                .thenReturn(detail))
-            .flatMap(detail ->
-                Flux.fromIterable(providers)
-                    .flatMap(provider -> provider
-                        .getAllType()
-                        .filter(type -> type.getId().equals(detail.getTargetType()))
-                        .singleOrEmpty()
-                        .flatMap(type -> provider.getDimensionById(type, detail.getTargetId())))
-                    .singleOrEmpty()
-                    .flatMapIterable(detail::toEntity)
-                    .switchIfEmpty(Flux.defer(() -> Flux.fromIterable(detail.toEntity())))
-            )
-            .as(settingService::save)
+
+        return settingService
+            .saveDetail(detailFlux)
             .thenReturn(true);
     }
 
     @GetMapping("/{targetType}/{target}")
     @SaveAction
-    public Mono<AuthorizationSettingDetail> getSettings(@PathVariable String targetType, @PathVariable String target) {
-
+    @Operation(summary = "获取权限详情")
+    public Mono<AuthorizationSettingDetail> getSettings(@PathVariable @Parameter(description = "权限类型") String targetType,
+                                                        @PathVariable @Parameter(description = "权限类型对应数据ID") String target) {
 
         return settingService
-            .createQuery()
-            .where(AuthorizationSettingEntity::getDimensionTarget, target)
-            .and(AuthorizationSettingEntity::getDimensionType, targetType)
-            .fetch()
-            .collectList()
-            .map(AuthorizationSettingDetail::fromEntity)
+            .getSettingDetail(targetType, target)
             ;
     }
 

jetlinks-manager/authentication-manager/src/main/java/org/jetlinks/community/auth/web/MenuController.java

@@ -1,5 +1,6 @@
 package org.jetlinks.community.auth.web;
 
+import io.swagger.v3.oas.annotations.Hidden;
 import org.hswebframework.web.api.crud.entity.TreeSupportEntity;
 import org.hswebframework.web.authorization.Authentication;
 import org.hswebframework.web.authorization.AuthenticationUtils;
@@ -32,6 +33,7 @@ import java.util.stream.Collectors;
 @RequestMapping("/menu")
 @Authorize
 @Resource(id = "menu", name = "菜单管理", group = "system")
+@Hidden
 public class MenuController implements ReactiveServiceCrudController<MenuEntity, String> {
 
     @Autowired

jetlinks-manager/authentication-manager/src/main/java/org/jetlinks/community/auth/web/OrganizationController.java

@@ -1,6 +1,10 @@
 package org.jetlinks.community.auth.web;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.hswebframework.web.api.crud.entity.PagerResult;
+import org.hswebframework.web.api.crud.entity.QueryOperation;
 import org.hswebframework.web.api.crud.entity.QueryParamEntity;
 import org.hswebframework.web.api.crud.entity.TreeSupportEntity;
 import org.hswebframework.web.authorization.annotation.*;
@@ -14,15 +18,15 @@ import reactor.core.publisher.Mono;
 @RequestMapping("/organization")
 @RestController
 @Resource(id = "organization", name = "机构管理")
+@Tag(name = "机构管理")
 public class OrganizationController {
-
     static String orgDimensionTypeId = "org";
-
     @Autowired
     private DefaultDimensionService dimensionService;
 
     @GetMapping("/_all/tree")
     @Authorize(merge = false)
+    @Operation(summary = "获取全部机构信息(树结构)")
     public Flux<DimensionEntity> getAllOrgTree() {
         return getAllOrg()
             .collectList()
@@ -31,6 +35,7 @@ public class OrganizationController {
 
     @GetMapping("/_all")
     @Authorize(merge = false)
+    @Operation(summary = "获取全部机构信息")
     public Flux<DimensionEntity> getAllOrg() {
         return dimensionService
             .createQuery()
@@ -40,7 +45,8 @@ public class OrganizationController {
 
     @GetMapping("/_query")
     @QueryAction
-    public Mono<PagerResult<DimensionEntity>> queryDimension(QueryParamEntity entity) {
+    @QueryOperation(summary = "查询结构列表")
+    public Mono<PagerResult<DimensionEntity>> queryDimension(@Parameter(hidden = true) QueryParamEntity entity) {
         return entity
             .toNestQuery(q -> q.where(DimensionEntity::getTypeId, orgDimensionTypeId))
             .execute(Mono::just)
@@ -49,6 +55,7 @@ public class OrganizationController {
 
     @PatchMapping
     @SaveAction
+    @QueryOperation(summary = "保存机构信息")
     public Mono<Void> saveOrg(@RequestBody Flux<DimensionEntity> entityFlux) {
         return entityFlux
             .doOnNext(entity -> entity.setTypeId(orgDimensionTypeId))
@@ -56,12 +63,12 @@ public class OrganizationController {
             .then();
     }
 
-    @DeleteMapping
+    @DeleteMapping("/{id}")
     @DeleteAction
-    public Mono<Void> deleteOrg(@RequestBody Flux<DimensionEntity> entityFlux) {
-        return entityFlux
-            .doOnNext(entity -> entity.setTypeId(orgDimensionTypeId))
-            .as(dimensionService::save)
+    @QueryOperation(summary = "删除机构信息")
+    public Mono<Void> deleteOrg(@PathVariable String id) {
+        return dimensionService
+            .deleteById(Mono.just(id))
             .then();
     }
 

jetlinks-manager/authentication-manager/src/main/java/org/jetlinks/community/auth/web/SystemConfigController.java

@@ -1,5 +1,7 @@
 package org.jetlinks.community.auth.web;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.hswebframework.ezorm.rdb.mapping.ReactiveRepository;
 import org.hswebframework.web.authorization.annotation.Authorize;
 import org.hswebframework.web.authorization.annotation.QueryAction;
@@ -15,6 +17,8 @@ import java.util.Map;
 @RequestMapping("/system/config")
 @RestController
 @Resource(id = "system-config", name = "系统配置")
+@Authorize
+@Tag(name = "系统配置")
 public class SystemConfigController {
 
     private final ReactiveRepository<SystemConfigEntity, String> repository;
@@ -26,6 +30,7 @@ public class SystemConfigController {
     @GetMapping("/front")
     @QueryAction
     @Authorize(ignore = true)
+    @Operation(summary = "获取前端配置信息")
     public Mono<Map<String, Object>> getFrontConfig() {
         return repository.findById("default")
             .map(SystemConfigEntity::getFrontConfig)
@@ -33,8 +38,8 @@ public class SystemConfigController {
     }
 
     @PostMapping("/front")
-    @QueryAction
     @SaveAction
+    @Operation(summary = "保存前端配置信息", description = "参数为json对象,可保存任意字段.")
     public Mono<Void> saveFrontConfig(@RequestBody Mono<Map<String, Object>> config) {
         return config
             .map(front -> SystemConfigEntity.front("default", front))

jetlinks-manager/authentication-manager/src/main/java/org/jetlinks/community/auth/web/UserDetailController.java

@@ -1,5 +1,7 @@
 package org.jetlinks.community.auth.web;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.AllArgsConstructor;
 import org.hswebframework.web.authorization.Authentication;
 import org.hswebframework.web.authorization.exception.UnAuthorizedException;
@@ -12,6 +14,7 @@ import reactor.core.publisher.Mono;
 @RestController
 @RequestMapping("/user/detail")
 @AllArgsConstructor
+@Tag(name = "用户信息接口")
 public class UserDetailController {
 
     private final UserDetailService userDetailService;
@@ -22,6 +25,7 @@ public class UserDetailController {
      * @return 用户详情
      */
     @GetMapping
+    @Operation(summary = "获取当前登录用户详情")
     public Mono<UserDetail> getCurrentLoginUserDetail() {
         return Authentication
             .currentReactive()
@@ -35,6 +39,7 @@ public class UserDetailController {
      * @return 用户详情
      */
     @PutMapping
+    @Operation(summary = "保存当前用户详情")
     public Mono<Void> saveUserDetail(@RequestBody Mono<SaveUserDetailRequest> request) {
         return Authentication
             .currentReactive()
@@ -43,4 +48,4 @@ public class UserDetailController {
             .flatMap(tp2 -> userDetailService.saveUserDetail(tp2.getT1().getUser().getId(), tp2.getT2()));
     }
 
-}
+}