技术整合1：Spring Boot整合Swagger3.0及Knife4j

1.Maven依赖引入

<!-- swagger3：访问路径http://ip:port/swagger-ui/index.html-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.SwaggerConfig配置类

package com.zhigong.heavenearth.config;
​
​
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
​
/**
 * @author 田治功
 * @description Swagger配置类
 * @date 2021-10-31 1:36
 */
@EnableOpenApi//该注解是Springfox-swagger框架提供的使用Swagger注解，该注解必须加
@EnableKnife4j//该注解是knife4j提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,如果你想使用这些增强功能就必须加该注解，否则可以不用加
@Configuration
public class SwaggerConfig {
    /**
     * 接口构建器
     *
     * @return
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhigong.heavenearth.controller"))
                .paths(PathSelectors.any())
                .build()
                .groupName("治功")
                .enable(true);
    }
​
    /**
     * Api页面信息配置
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("技术学习实践整合")
                .description("新技术整合学习及配置案例DEMO")
                .contact(new Contact("治功", "https://juejin.cn/user/2806404106423112", "邮箱"))
                .version("V1.0")
                .build();
    }
}

3.Controller

package com.zhigong.heavenearth.controller;
​
​
import com.zhigong.heavenearth.common.Result;
import com.zhigong.heavenearth.dto.SkillStudyPlanDTO;
import com.zhigong.heavenearth.service.SkillStudyPlanService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
​
import javax.annotation.Resource;
​
/**
 * @author 田治功
 * @description 技术学习规划表控制器
 * @date 2021-10-31 1:36
 */
@Api(tags = "技术学习规划表")
@RestController
@RequestMapping("/skillStudyPlan")
public class SkillStudyPlanController {
​
    @Resource
    private SkillStudyPlanService skillStudyPlanService;
​
    @ApiOperation("插入技术学习规划")
    @PostMapping("insertPlan")
    public Result insertPlan(@RequestBody SkillStudyPlanDTO skillStudyPlanDTO) {
        return skillStudyPlanService.insertPlan(skillStudyPlanDTO);
    }
​
    @ApiOperation("查询所有技术学习规划")
    @GetMapping("selectAll")
    public Result selectAll() {
        return skillStudyPlanService.selectAll();
    }
}

4.常用注解

注解	说明
@Api	模块配置，用在Controller类上，描述Api接口
@ApiOperation	接口配置，用在方法上，描述接口方法
@ApiParam	方法参数配置，用在入参中或注解中
@Apilgnore	忽略此接口不生成文档
@ApiModel	用于类，表示对类进行说明，描述一个Model的信息
@ApiModelProperty	用于属性，表示对类中变量的说明，描述一个model的属性
@ApiImplicitParams	用在方法上包含一组参数说明
@ApiImplicitParam	用来注解来给方法入参增加说明
@ApiResponses	用于表示一组响应结果
@ApiResponse	用在@ApiResponses中，一般用于表达一个错误的响应信息

5.接口文档界面

使用浏览器访问http://host:port/swagger-ui/index.html即可打开接口文档界面

6.Knife4j增强方案

1. 引入Maven依赖

   <!-- knife4j：swagger增强方案，使用doc布局方式 -->
   <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>knife4j-spring-boot-starter</artifactId>
       <version>3.0.3</version>
   </dependency>
   

2. knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，已在上述的SwaggerConfig配置类中配置了Swagger，故无需单独为Knife4j配置

3. 浏览器输入地址:http://host:port/doc.html即可打开接口文档界面