Spring Boot整合Swagger3.0及Knife4j_springboot3整和knife4-CSDN博客

本文链接：https://blog.csdn.net/zlfjavahome/article/details/130392873

一、什么是 Swagger

Swagger是一组围绕 OpenAPI 规范构建的开源工具，可帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具包括：

Swagger Editor – 基于浏览器的编辑器，您可以在其中编写 OpenAPI 规范。
Swagger UI – 将 OpenAPI规范呈现为交互式 API 文档。
swagger2于17年停止维护，现在最新的版本为 Swagger3（Open Api3）。

二、什么是knife4j

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

三、依赖引入

<!--springfox-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

<!--knife4j-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

<!--引入美化bootstrap-UI-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.8.5</version>
</dependency>

四：详细例子

配置文件加上@EnableOpenApi、@Configuration 会自动开启配置，启动类不需要加任何注解

@EnableOpenApi//该注解是Springfox-swagger框架提供的使用Swagger注解，该注解必须加
@EnableKnife4j//该注解是knife4j提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,如果你想使用这些增强功能就必须加该注解，否则可以不用加
@Configuration
public class SwaggerConfig {
/**
 * 接口构建器
 *
 * @return
 */
@Bean
public Docket docket() {
    return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
            //用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
            .apiInfo(apiInfo())
            //设置哪些接口暴露给Swagger展示
            .select()
             // (第一种方式)扫描所有有注解的api，用这种方式更灵活
            .apis( RequestHandlerSelectors.withMethodAnnotation( ApiOperation.class ) )

            // (第二种方式)扫描指定包中的swagger注解
            .apis(RequestHandlerSelectors.basePackage("com.swagger_knife4j.swagger4j.controller"))//构建API

            // (第三种方式)扫描所有
            .apis(RequestHandlerSelectors.any())
            .paths( PathSelectors.any() )

            .paths(PathSelectors.any())
            .build()
            .groupName("XimenesChen")
            .enable(true);
  }

   /**
     * 添加摘要信息
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     */
   private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("整合knife-4j，swaggerui基本注解")//标题
                    .description("整合knife-4j，swaggerui基本注解-描述")//描述
                    .contact(new Contact("cxm", "https://mp.csdn.net/mp_blog/manage/article?spm=1001.2014.3001.5114", "cristianoxm@qq.com"))
                    .version("V2.05")
                    .build();
   }
}

实体类

@AllArgsConstructor
@NoArgsConstructor
@Builder
@Data
@ApiModel("common-result")
public class Result<T> {
    @ApiModelProperty(value = "返回状态码")
    private Integer code;
    @ApiModelProperty(value = "返回信息")
    private String message;
    @ApiModelProperty(value = "返回实体信息")
    private T data;
}

控制器：

@Api(tags = "技术学习规划表-控制器")//@Api：用在类上，说明该类的作用
@RestController
@RequestMapping("/skillStudyPlan")
public class SkillStudyPlanController {
    @ApiOperation("插入技术学习规划")//@ApiOperation：注解来给API增加方法说明
    @PostMapping("insertPlan")
    @ApiResponses({
		@ApiResponse(code = 200, message = "请求成功",response = Result.class),
		@ApiResponse(code = 400, message = "404错误",response = Result.class),
		@ApiResponse(code = 404, message = "路径不存在",response = Result.class)
	})
    public Result<ResponseB> insertPlan(@ApiParam @RequestBody(required = false) SkillStudyPlanDTO skillStudyPlanDTO) {
        ResponseB build = ResponseB.builder().message("ss").code(200).data("data").build();
        System.out.println(skillStudyPlanDTO);
        return new Result<>(200,"ok",build);
    }

    @ApiOperation("查询所有技术学习规划")
    @GetMapping("selectAll")
    public String selectAll(@RequestParam String name,@RequestParam(required = false) Integer age) {
        System.out.print(name);
        System.out.print(age);
        return "success";
    }

    @PostMapping("pageHelp")
    @ApiOperation(value = "分页获取标签列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name="pageNo",value="请求页数",required = false,dataType="Integer",paramType="query"
            ),
            @ApiImplicitParam(name="pageSize",value="请求页大小",required = false,dataType="Integer",paramType="query"),
    })
    //header：请求头
    //query：?param=value的形式
    //path：路径，Restful风格接口
    //body：请求体
    //form：以form表单的形式提交
   @ApiResponses({
		@ApiResponse(code = 200, message = "请求成功",response = Result.class),
		@ApiResponse(code = 400, message = "请求参数没填好",response = Result.class),
		@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对",response = Result.class)
	})
    public Result<ResponseA> pageHelp(@RequestParam Integer pageNo, @RequestParam Integer pageSize){
        ResponseA build = ResponseA.builder().message("ss").code(200).data("data").build();
        return new Result<>(200,"ok",build);
    }
}