api文档——knife4j

1)简介

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

gitee地址：https://gitee.com/xiaoym/knife4j

官方文档：https://doc.xiaominfo.com/

效果演示：http://knife4j.xiaominfo.com/doc.html

2)核心功能

该UI增强包主要包括两大核心功能：文档说明 和 在线调试

3)快速集成

在 【study-leadnews-core-controller】工程中pom.xml文件中引入knife4j的依赖,并删除掉原来的swagger的依赖如下：

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

注意,如果是高版本springboot已经去除掉了validation 还需要在【study-leadnews-core-controller】工程中添加依赖，因为knife4j需要使用到他

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

API文档技术会扫描指定的【Controller】，而所有微服务都依赖了study-leadnews-core-controller，我们可以直接在该工程中实现对Swagger的配置， 在study-leadnews-core-controller工程的config包中添加一个配置类，代码如下：

在【SwaggerConfiguration.java】上添加【@EnableSwagger2】和【@EnableKnife4j】注解,代码如下：

@Configuration
@EnableSwagger2
@EnableKnife4j //启动动态配置
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {

    /**
     * 创建API文档信息
     * @return
     */
    @Bean
    public Docket buildDocket() {
        HashSet<String> strings = new HashSet<>();
        strings.add("application/json");

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                //设置返回值数据类型为json
                .produces(strings)
                .select()
                // 要扫描的API(Controller)基础包
                .apis(RequestHandlerSelectors.basePackage("com.itheima"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 定义Swagger文档信息
     * @return
     */
    private ApiInfo buildApiInfo() {
        Contact contact = new Contact("黑马程序员","","");
        return new ApiInfoBuilder()
                .title("黑马头条-平台管理API文档")
                .description("平台管理服务api")
                .contact(contact)
                .version("1.0.0").build();
    }
}

以上有两个注解需要特别说明，如下表：

@EnableSwagger2	该注解是Springfox-swagger框架提供的使用Swagger注解，该注解必须加
@EnableKnife4j	该注解是knife4j提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,如果你想使用这些增强功能就必须加该注解，否则可以不用加

在浏览器输入地址：http://localhost:你项目的端口号/doc.html即可