knife4j增强swagger

背景

swagger很好用，但是UI不够友好

导入maven依赖

使用maven-search在common模块中导入依赖

 <!--  knife4j      --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.3</version></dependency>

改造前端的页面

在这里插入图片描述

将URL改成doc.html

在这里插入图片描述

前台如何打开

在这里插入图片描述

如何被swagger捕获到

controller类上的注解 @Api("用户信息管理")

@Api("用户信息管理")
@RestController
@RequestMapping("/test/user")
public class TestController extends BaseController

方法上的注解 @ApiOperation("获取用户列表")

    @ApiOperation("获取用户列表")@GetMapping("/list")public R<List<UserEntity>> userList(){List<UserEntity> userList = new ArrayList<UserEntity>(users.values());return R.ok(userList);}

实体类上的注解 @ApiModel 和 @ApiModelProperty

@ApiModel(value = "UserEntity", description = "用户实体")
class UserEntity
{@ApiModelProperty("用户ID")private Integer userId;
}

如何加上swagger注解

这个工作交给ai来完成

在这里插入图片描述

如何解决响应参数是空的问题

响应经过AjaxResult 封装，是HashMap，swagger识别不到

public class AjaxResult extends HashMap<String, Object>
{

修改前

调用的是 success方法，返回的是 AjaxResult方法

在这里插入图片描述

修改后

修改后调用的是R.ok方法，返回的是R<List<TaskDetails>>，需要指定泛型

在这里插入图片描述

@ApiOperation("查询工单详情列表")
@PreAuthorize("@ss.hasPermi('manage:taskDetails:list')")
@GetMapping("/list")
public R<List<TaskDetails>> list(TaskDetails taskDetails)
{startPage();List<TaskDetails> list = taskDetailsService.selectTaskDetailsList(taskDetails);return R.ok(list);
}

对应的实体类加上注解

实体类

@ApiModel(description = "工单详情对象")
public class TaskDetails extends BaseEntity
{private static final long serialVersionUID = 1L;/** 详情Id */@ApiModelProperty(value = "详情Id")private Long detailsId;/** 工单Id */@Excel(name = "工单Id")@ApiModelProperty(value = "工单Id")private Long taskId;}

基类

@ApiModel(description = "Entity基类")
public class BaseEntity implements Serializable
{private static final long serialVersionUID = 1L;/** 搜索值 */@ApiModelProperty(value = "搜索值")@JsonIgnoreprivate String searchValue;/** 创建者 */@ApiModelProperty(value = "创建者")private String createBy;/** 创建时间 */@ApiModelProperty(value = "创建时间")@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")private Date createTime;}

此时就有了响应类型

在这里插入图片描述

调用的时候是需要headers请求头的

在这里插入图片描述

返回的内容

在这里插入图片描述

其他的配置信息都可以在配置类中设置

src/main/java/com/dkd/web/core/config/SwaggerConfig.java

在这里插入图片描述

private ApiInfo apiInfo()
{// 用ApiInfoBuilder进行定制return new ApiInfoBuilder()// 设置标题.title("标题：帝可得管理系统_接口文档")// 描述.description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")// 作者信息.contact(new Contact(ruoyiConfig.getName(), null, null))// 版本.version("版本号:" + ruoyiConfig.getVersion()).build();
}