Spring Boot 1.5.10项目引入knife4j接口文档

深藏阁楼爱情的钟 2023-09-29 18:00 11阅读 0赞

## 介绍 ##

knife4j是一个在线接口文档项目，对swaggger2进行增强，页面更加美观，功能更加强大

## 背景 ##

在前后端分离的趋势下，团队一直没有接口文档规范，联调接口全凭一个个接口去代码里扒，后端同事忙起来，前端甚至干不了活，所以引入Knife4j。目的是提高开发效率，一定程度方便查找接口避免重复开发

## 版本 ##

*  spring boot版本1.5.10.RELEAS
 *  knife4j版本2.0.4

## 配置 ##

*  先引入knife4j依赖

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

*  添加Knife4jConfig.java配置文件

/**
     * knife4j配置信息
     *
     * @author wuxl
     * @since 2022-11-11
     */
    //@EnableSwagger2WebMvc
    @Configuration
    @EnableSwagger2
    @EnableKnife4j
    //@Profile("!prod")
    public class Knife4jConfig {
    
        @Bean
        public Docket docket() {
            // head参数
            List<Parameter> parameters = new ArrayList<>();
            ParameterBuilder parameterBuilder = new ParameterBuilder();
            // 设置Cookie中token属性名
            parameterBuilder.name("Cookie")
                    .description("携带用户JWT-TOKEN")
                    .defaultValue("")
                    .modelRef(new ModelRef("string"))
                    .parameterType("header")
                    .required(false)
                    .build();
            parameters.add(parameterBuilder.build());
    
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .groupName("新版ABP")
                    .apiInfo(adminApiInfo())
                    .select()
                    // 配置包扫描路径
                    .apis(RequestHandlerSelectors.basePackage("com.linkus.abp.controller"))
                    .paths(PathSelectors.any())
                    .build()
                    .globalOperationParameters(parameters);
            return docket;
        }
    
        private ApiInfo adminApiInfo() {
            return new ApiInfoBuilder()
                    .title("新版ABP系统-API文档")
                    .description("新版ABP系统 RESTful APIs")
                    .version("1.0")
                    .contact(new Contact("wuxl", "http://ip/application-name/home.action", "wuxl@123456.com"))
                    .build();
        }
    }

浏览器访问http://localhost:18095/linkus-abp/doc.html

效果

![在这里插入图片描述][7222b8913e964085b60fa098918f041b.png]

## 使用说明 ##

### 一、controller上注解 ###

#### 代码 ####

@Api(tags = "计划编制模块")
    @ApiSupport(author = "wuxl", order = 1)
    @RestController
    @RequestMapping("/hello")
    public class HelloController {

#### 说明 ####

*  @Api(tags = “计划编制模块”)

设置controller名称

*  @ApiSupport(author = “wuxl”, order = 1)

设置controller作者和排序

#### 效果 ####

![在这里插入图片描述][929dda2d1e0948d2aad1376aa0ca6cf3.png]

### 二、controller下接口描述c ###

#### 代码 ####

@ApiOperation(value = "查询经营计划信息", notes = "全周期页签")

#### 说明 ####

@ApiOperation(value = “查询经营计划信息”, notes = “全周期页签”)

设置接口描述和接口备注

#### 效果 ####

![在这里插入图片描述][c96449f0ac4f45ecb94967a3e45db0e3.png]

### 三、controller下接口排序 ###

#### 代码 ####

@ApiOperationSupport(order = 10)

#### 说明 ####

@ApiOperationSupport(order = 10)

在线文档controller下的接口进行排序，也可以设置具体接口的作者

#### 效果 ####

![在这里插入图片描述][34865542317c45609dbfb79dd03ffeeb.png]

### 四、接口入参 ###

#### 代码 ####

@ApiOperation(value = "上移经营计划里程碑", notes = "全周期页签")
    @ApiImplicitParams({@ApiImplicitParam(name = "mstId", value = "当前里程碑id", required = true),
            @ApiImplicitParam(name = "preMstId", value = "上移到的上一个里程碑id", required = true)})
    @ApiOperationSupport(order = 70)
    @PostMapping("/abpOop/mst/up/{abpOopId}/{mstId}")
    public CommonResult moveUpAbpOopMst(@PathVariable ObjectId abpOopId, @PathVariable ObjectId mstId,
                                        @RequestParam("preMstId") ObjectId preMstId) {

#### 说明 ####

@ApiImplicitParams

设置入参描述，是否必填，单个参数时用@ApiImplicitParam即可，name也可以不填

#### 效果 ####

![在这里插入图片描述][7a90dc9b664f4230a8149edc36a1e715.png]

### 五、接口入参DTO对象 ###

#### 代码 ####

@ApiOperation(value = "修改经营计划基本信息", notes = "HC页签，第一次编辑新增和基本信息页签编辑")
    @ApiOperationSupport(order = 150)
    @PostMapping("/abpOop/pl/{abpOopId}")
    public CommonResult updateBaseInfo(@PathVariable ObjectId abpOopId,
                                       @RequestBody @Valid BaseInfoDTO baseInfoDTO) {
        planningService.updateBaseInfo(abpOopId, baseInfoDTO);

/**
     * 基本信息数据传输对象
     *
     * @author wuxl
     * @since 2022-11-21
     */
    @Data
    @FieldDefaults(level = AccessLevel.PRIVATE)
    @ApiModel(value = "BaseInfoDTO", description = "基本信息数据传输对象")
    public class BaseInfoDTO {
    
        @NotNull(message = "客户预算类型不能为空")
        @ApiModelProperty(value = "客户预算类型", required = true)
        ObjectId customBudgetTypeId;
    
        @NotNull(message = "合同类型不能为空")
        @ApiModelProperty(value = "合同类型", required = true)
        ObjectId contractTypeId;
    
        @NotNull(message = "项目类型不能为空")
        @ApiModelProperty(value = "项目类型", required = true)
        ObjectId prjTypeId;
    
        @NotNull(message = "省份不能为空")
        @ApiModelProperty(value = "省份", required = true)
        ObjectId provId;
    
        @NotNull(message = "项目等级不能为空")
        @ApiModelProperty(value = "项目等级", required = true)
        ObjectId prjLevelId;
    
        @NotNull(message = "管控周期开始不能为空")
        @ApiModelProperty(value = "管控周期开始", required = true)
        String startTime;
    
        @NotNull(message = "管控周期结束不能为空")
        @ApiModelProperty(value = "管控周期结束", required = true)
        String endTime;
    
        /**
         * 产品线占比列表
         */
        List<PlDTO> plDTOs;
    }

#### 说明 ####

*  @ApiModel(value = “BaseInfoDTO”, description = “基本信息数据传输对象”)

设置对象描述

*  @ApiModelProperty(value = “管控周期结束”, required = true)

设置对象属性描述和是否必填

#### 效果 ####

![在这里插入图片描述][fe74f6be521c4439ab9e16c019b80cb3.png]

### 六、接口返回参数VO对象 ###

#### 代码 ####

@ApiOperation(value = "查询经营计划基本信息", notes = "基本信息页签，根据经营计划id查询基础信息，包括客户预算类型、合同类型、项目类型和产品线传统业务占比和三新占比（OSS订单占比、企业上云订单占比、数字化运营订单占比）集合")
    @ApiOperationSupport(order = 130)
    @GetMapping("/abpOop/pl/{abpOopId}")
    public CommonResult<BaseInfoVO> queryBaseInfo(@PathVariable ObjectId abpOopId) {
        BaseInfoVO baseInfoVO = planningService.queryBaseInfo(abpOopId);
        return CommonResult.success(baseInfoVO);
    }

/**
     * 经营计划基本信息视图对象
     *
     * @author wuxl
     * @since 2022-11-21
     */
    @Data
    @FieldDefaults(level = AccessLevel.PRIVATE)
    @ApiModel(value = "BaseInfoVO", description = "经营计划基本信息视图对象")
    public class BaseInfoVO {
    
        @ApiModelProperty(value = "省份信息")
        TeIdNameCn prov;
    
        @ApiModelProperty(value = "管控周期:开始时间")
        @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
        Date startTime;
    
        @ApiModelProperty(value = "管控周期:结束时间")
        @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
        Date endTime;
    
        /**
         * buCode
         */
        @ApiModelProperty(value = "buCode")
        String buCode;
    
        /**
         * 项目等级
         */
        @ApiModelProperty(value = "项目等级")
        TeIdNameCn prjLevel;
    
        /**
         * 客户预算类型
         */
        @ApiModelProperty(value = "客户预算类型")
        TeIdNameCn customBudgetType;
    
        /**
         * 合同类型
         */
        @ApiModelProperty(value = "合同类型")
        TeIdNameCn contractType;
    
        /**
         * 项目类型
         */
        @ApiModelProperty(value = "项目类型")
        TeIdNameCn prjType;
    
        /**
         * 产品线传统业务占比和三新占比（OSS订单占比、企业上云订单占比、数字化运营订单占比）集合，排除产品线占比为0的
         */
        @ApiModelProperty(value = "产品线传统业务占比和三新占比（OSS订单占比、企业上云订单占比、数字化运营订单占比）集合，排除产品线占比为0的")
        List<PlVO> plVOs;
    }

#### 说明 ####

*  @ApiModel(value = “BaseInfoVO”, description = “经营计划基本信息视图对象”)

设置对象描述

*  @ApiModelProperty(value = “项目类型”)

设置对象属性描述和是否必传

#### 效果 ####

![在这里插入图片描述][06aed3bd0bf94a9f97ca7af83ee535cb.png]

### 七、生产功能禁用knife4j ###

#### 方式一： ####

spring.profiles.active=prod

@Configuration
    @EnableSwagger2
    @EnableKnife4j
    @Profile("!prod")
    public class Knife4jConfig {

#### 方式二： ####

knife4j.production=false

#### 效果 ####

![在这里插入图片描述][b8573566c2864e46b653db7a7d41ea41.png]

### 八、配置登录密码 ###

配置

# knife4j增强配置
    knife4j.production=false
    knife4j.basic.enable=true
    knife4j.basic.username=admin
    knife4j.basic.password=admin

效果  
![在这里插入图片描述][9aaf1570d3494225bd93715bccc37a11.png]

[7222b8913e964085b60fa098918f041b.png]: https://img-blog.csdnimg.cn/7222b8913e964085b60fa098918f041b.png
[929dda2d1e0948d2aad1376aa0ca6cf3.png]: https://img-blog.csdnimg.cn/929dda2d1e0948d2aad1376aa0ca6cf3.png
[c96449f0ac4f45ecb94967a3e45db0e3.png]: https://img-blog.csdnimg.cn/c96449f0ac4f45ecb94967a3e45db0e3.png
[34865542317c45609dbfb79dd03ffeeb.png]: https://img-blog.csdnimg.cn/34865542317c45609dbfb79dd03ffeeb.png
[7a90dc9b664f4230a8149edc36a1e715.png]: https://img-blog.csdnimg.cn/7a90dc9b664f4230a8149edc36a1e715.png
[fe74f6be521c4439ab9e16c019b80cb3.png]: https://img-blog.csdnimg.cn/fe74f6be521c4439ab9e16c019b80cb3.png
[06aed3bd0bf94a9f97ca7af83ee535cb.png]: https://img-blog.csdnimg.cn/06aed3bd0bf94a9f97ca7af83ee535cb.png
[b8573566c2864e46b653db7a7d41ea41.png]: https://img-blog.csdnimg.cn/b8573566c2864e46b653db7a7d41ea41.png
[9aaf1570d3494225bd93715bccc37a11.png]: https://img-blog.csdnimg.cn/9aaf1570d3494225bd93715bccc37a11.png