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

wuxlcoding
370 阅读2分钟

介绍

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

背景

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

版本

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

配置

  • 先引入knife4j依赖
<!-- knife4j官方starter版本管理，包含Swagger2 -->
<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

效果

image.png

使用说明

一、controller上注解

代码

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

说明

  • @Api(tags = "计划编制模块")

设置controller名称

  • @ApiSupport(author = "wuxl", order = 1)

设置controller作者和排序

效果

image.png

二、controller下接口描述

代码

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

说明

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

设置接口描述和接口备注

效果

image.png

三、controller下接口排序

代码

@ApiOperationSupport(order = 10)

说明

@ApiOperationSupport(order = 10)

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

效果

image.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也可以不填

效果

image.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)

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

效果

image.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 = "项目类型")

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

效果

image.png

七、生产功能禁用knife4j

方式一：

spring.profiles.active=prod

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

方式二：

knife4j.production=false

效果

image.png

八、配置登录密码

配置

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

效果

image.png

avatar
文章
阅读
粉丝