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 = "搜索值")
    @JsonIgnore
    private 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();
}