Spring Boot整合Swagger3.0及Knife4j

快来打我* 2023-10-09 20:07 93阅读 0赞

### 一、什么是 [Swagger][] ###

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

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

### 二、什么是knife4j ###

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

### 三、依赖引入 ###

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
    
    
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.3</version>
    </dependency>
    
    
    <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);
        }
    }

### 五：Swagger注解详解 ###

就那几个，常用的注解，上边例子都有，特殊需求再网上再扒拉吧

[Swagger]: https://so.csdn.net/so/search?q=Swagger&spm=1001.2101.3001.7020
[OpenAPI]: https://so.csdn.net/so/search?q=OpenAPI&spm=1001.2101.3001.7020
[swagger2]: https://so.csdn.net/so/search?q=swagger2&spm=1001.2101.3001.7020