spring boot整合Knife4j取代swagger2.0

BillDavidup

已于 2022-07-28 21:59:41 修改

阅读量489

点赞数 1

于 2022-07-26 22:54:52 首次发布

本文链接：https://blog.csdn.net/qq_21922755/article/details/126004411

版权

最佳实践同时被 2 个专栏收录

3 篇文章 0 订阅

订阅专栏

SpringBoot

2 篇文章 0 订阅

订阅专栏

零、写在前面

swagger2已升级为knife4j

一、整合注意

本文示例代码请从github下载 https://github.com/BillDavidup/study-api
knife4j官网https://doc.xiaominfo.com/
不同knife4j的版本和spring boot的版本不兼容会有冲突，导致启动类StudyApiWebApplication启动失败
整合的knife4j版本和spring boot版本如下

// Spring boot
<parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
     <version>2.4.5</version>
</parent>
// knife4j
<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
     <version>2.0.4</version>
</dependency>

二、整合步骤

1.将knife4j的jar包注入在pom.xml中

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

2.新建Knife4jConfig配置类，配置内容如下：

package com.dening.study.api.web.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Knife4jConfig {
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        // 文档访问地址 该服务的ip:port/doc.html
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("study-api")
                        .description("对外提供HTTP服务的接口文档")
                        .termsOfServiceUrl("http://study-api.com/doc.html")
                        .contact(new Contact("study-api模板项目", "git@github.com:BillDavidup/study-api.git", "1336038558@qq.com"))
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("all")
                .select()
                //指定Controller扫描路径。可以不具体到controller，它会扫描指定路径下的所有
                .apis(RequestHandlerSelectors.basePackage("com.dening.study.api.web.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

3.使用Knife4j的配置注解

请求参数

@ApiModel
public class ProjectInfoReq {
    @ApiModelProperty(required = true, name = "项目ID", value = "999")
    Long projectId;
    @ApiModelProperty(name = "项目名称", value = "高级项目")
    String projectName;
}

返回值

@ApiModel()
public class ProjectInfoDTO {
    @ApiModelProperty(required = true, name = "项目ID", value = "999")
    Long projectId;
    @ApiModelProperty(name = "项目信息实体", value = "项目信息实体")
    ProjectInfoVO infoVO;
}

返回值内置VO

@ApiModel
public class ProjectInfoVO {
    @ApiModelProperty(name = "项目名称", value = "高级项目")
    String projectName;
    @ApiModelProperty(name = "项目描述", value = "该项目用于swagger接口文档的测试")
    String projectDesc;
}

controller接口

@RestController
@RequestMapping(value = "/api/swagger/demo")
public class ProjectSwaggerDemoController {

    @ApiOperation(value = "/api/swagger/demo/getProjectInfo")
    @PostMapping("/getProjectInfo")
    public ProjectInfoDTO getProjectInfo(@RequestBody ProjectInfoReq req) {

        ProjectInfoDTO dto = new ProjectInfoDTO();
        Long projectId = req.getProjectId();
        dto.setProjectId(projectId);

        ProjectInfoVO infoVO = new ProjectInfoVO();
        String projectName = req.getProjectName();
        infoVO.setProjectName(projectName);
        infoVO.setProjectDesc("swagger测试项目");
        dto.setInfoVO(infoVO);

        return dto;
    }
}