SpringBoot整合knife4j基本使用

一、SpringBoot依赖和实例代码准备

本实例基于SpringBoot搭建，所需要的配置和依赖很少，下面添加主要的依赖

<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
     <version>1.9.6</version>
 </dependency>
 <dependency>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-web</artifactId>
 </dependency>

上面已经添加了相关的依赖，下面构建controller包，应对于项目开发，这里准备俩个不同的controller，其中admin标识后台controller接口，user标识前台应用的controller

其中controller里面的内容如下，注意需要有controller相关注解标注

/**
 * @Author zhangyu
 * @Date 2020/6/15
 * @Description
 **/
@RequestMapping("/admin/user")
@RestController
public class AdminUserRestController {
    @GetMapping("/add")
    public ApiResponse add() {
        return ApiResponse.ofSuccess("add");
    }
    @GetMapping("/delete")
    public ApiResponse delete() {
        return ApiResponse.ofSuccess("delete");
    }
    @GetMapping("/update")
    public ApiResponse update() {
        return ApiResponse.ofSuccess("update");
    }
    @GetMapping("/list")
    public ApiResponse list() {
        return ApiResponse.ofSuccess("list");
    }
}

其中ApiResponse就是后端返回前端的响应类Result

二、配置和页面展示

上面已经准备了基本的API接口，下面进行swagger的配置

/**
 * @Author zhangyu
 * @Date 2020/6/15
 * @Description
 **/

@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
@ConditionalOnProperty(value = {"knife4j.enable"}, matchIfMissing = true)
public class Swagger2Config {

    /**
     * 前台API分组
     *
     * @return
     */
    @Bean(value = "indexApi")
    public Docket indexApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("前台API分组")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.user"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 后台API分组
     *
     * @return
     */
    @Bean(value = "adminApi")
    public Docket adminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("后台API分组")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.admin"))
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui RESTful APIs")
                .description("swagger-bootstrap-ui")
                .termsOfServiceUrl("http://localhost:8999/")
                .contact("[email protected]")
                .version("1.0")
                .build();
    }

}

上面代码中构建了俩个分组，其中第一个分组主要处理前台部分的API，第二个分组主要处理后台部分的API，apiInfo构建API接口的描述信息

三、测试

swagger-bootstrap-ui默认访问地址是：http://$host:${port}/doc.html

四、主要注解

（一）@Api

表示这个类是Swagger的资源，该注解会被Swagger扫描到，该注解可以自定义显示的导航栏标签的名称tag

@RequestMapping("/admin/category")
@RestController
@Api(value = "商品分类接口", tags = "商品分类接口")
public class AdminCategoryRestController {
	//...
}

（二）@ApiOperation

用在方法上，说明方法的作用
@ApiOperation注解中的tags属性做更细粒度的接口分类定义，该注解可以用于多个不同的controller的分组

@RequestMapping("/admin/user")
@RestController
public class AdminUserRestController {

    @ApiOperation(value = "添加分类", tags = "商品分类接口")
    @GetMapping("/add")
    public ApiResponse add() {
        return ApiResponse.ofSuccess("add");
	}
}

上图可以看到在另外的controller中定义的接口方法是可以分属到其他的接口tag下的

（三）@ApiIgnore

忽略掉指定的接口和类，在开发中肯定存在一些用于跳转路由的controller，那么其实这部分是不需要把接口呈现给其他开发人员的，所以就可以通过@ApiIgnore注解忽略掉该注解

@RequestMapping("/admin/user")
@RestController
@ApiIgnore
public class AdminUserRestController {
	//...
}

参考文档：
https://doc.xiaominfo.com/guide/useful.html#java%E5%BC%80%E5%8F%91