Spring Boot 集成 Swagger 2 并配置 knife4j 主题

开发环境

Spring boot 2.3.1

引入依赖

1
2
implementation 'io.springfox:springfox-swagger2:2.9.2'  // 版本不能是最新版3.0.0
implementation 'com.github.xiaoymin:knife4j-spring-boot-starter:2.0.4'

添加配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
 

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
                .groupName("2.X版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.new2"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
  
  private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
                   .title("单词计数服务") //设置文档的标题
                   .description("单词计数服务 API 接口文档") // 设置文档的描述
                   .version("1.0.0") // 设置文档的版本信息-> 1.0.0 Version information
                   .termsOfServiceUrl("http://www.baidu.com") // 设置文档的License信息->1.3 License information
                   .build();
   }

}

编写内容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
/**
 * 权限控制器.
 * @author yuhanliu
 */
@RestController
@RequestMapping("/api/v1/permissions")
@Api("权限控制器")
public class PermissionController {

  @Resource
  private PermissionService permissionService;

  @Resource
  private ModelMapper modelMapper;

  @Resource
  private SecurityUtil securityUtil;

  /**
   * 添加权限.
   * @param permissionDto 权限
   * @return ApiResponse
   */
  @PostMapping("")
  @PreAuthorize("hasAnyAuthority('permission:add', 'permission:all')")
  @ApiOperation(value = "添加权限")
  @ApiImplicitParam(name = "permissionDto", required = true, dataTypeClass = PermissionDto.class,  dataType = "PermissionDto")
  public ApiResponse permission(@RequestBody @Validated PermissionDto permissionDto) {
    // 校验 Parent Permission
    String parentId = permissionDto.getParent();
    if (StrUtil.isNotBlank(parentId)) {
      if (!permissionService.getById(parentId).isPresent()) {
        return ApiResponse.ofStatus(StatusEnum.PARENT_PERMISSION_NOT_FOUND, parentId);
      }
    }
    // 校验 code 不重复
    String code = permissionDto.getCode();
    if (permissionService.getByCode(code).isPresent()) {
      return ApiResponse.ofStatus(StatusEnum.PERMISSION_ALREADY_EXIST, code);
    }
    // 补足字段
    Permission permission = new Permission();
    modelMapper.map(permissionDto, permission);
    permission.setId(IdUtil.simpleUUID());
    permission.setCreateBy(securityUtil.getUserId());
    // 存储权限
    return ApiResponse.ofSuccess(permissionService.add(permission));
  }

  /**
   * 删除某权限.
   * @param id 权限id
   * @return ApiResponse
   */
  @DeleteMapping("/{id}")
  @PreAuthorize("hasAnyAuthority('permission:del', 'permission:all')")
  @ApiOperation("删除权限")
  @ApiImplicitParam(name = "id", value = "权限的32位uuid",required = true)
  public ApiResponse permission(@PathVariable String id) {
    permissionService.deleteById(id);
    return ApiResponse.ofSuccess(id);
  }
}

注意参数一定要全,比如 name、value、dataType、dataTypeClass 这些。


knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案

knife4j-spring-boot-single-demo

updatedupdated2020-07-272020-07-27
加载评论