在前后端分离项目中使用knife4j作为接口API文档。

knife4j

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

knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j。

核心功能

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

文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，使用swagger-bootstrap-ui能根据该文档说明，对该接口的使用情况一目了然。

在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，而不必通过其他测试工具测试接口是否正确,简介、强大。

UI增强

同时，swagger-bootstrap-ui在满足以上功能的同时，还提供了文档的增强功能，这些功能是官方swagger-ui所没有的，每一个增强的功能都是贴合实际,考虑到开发者的实际开发需要,是比不可少的功能，主要包括：

个性化配置：通过个性化ui配置项，可自定义UI的相关显示信息

离线文档：根据标准规范，生成的在线markdown离线文档，开发者可以进行拷贝生成markdown接口文档，通过其他第三方markdown转换工具转换成html或pdf，这样也可以放弃swagger2markdown组件

接口排序：自1.8.5后，ui支持了接口排序功能，例如一个注册功能主要包含了多个步骤,可以根据swagger-bootstrap-ui提供的接口排序规则实现接口的排序，step化接口操作，方便其他开发者进行接口对接

具体配置：

导入依赖：

  <!--bootstrap-ui-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

如果只导入第一个starter只可以用新版的界面，这里导入之前配置swagger2的依赖开源同时使用swagger的ui界面和knife4j的新UI界面

配置类

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfigurer {


    @Value("${swagger.enable}")
    private boolean enable;


    @Value("${swagger.host}")
    private String swaggerHost;


    /**
     * 注入docket（swagger-ui）
     */
    @Bean
    protected Docket docket(){

        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("")
                .description("")
                .version("0.1")
                .contact(new Contact(", "", ""))
                .build();


        return new Docket(DocumentationType.SWAGGER_2)
                .host(swaggerHost)  //指定路径当前机器ip，动静分离，跨域需要设置。
                .enable(enable)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage(""))//扫描
                .paths(PathSelectors.any())
                .build();
    }
}

编写配置类内部和swagger2并无差别，只需在原来的
@Configuration
@EnableSwagger2
两个注解上加上
@EnableKnife4j

Swagger2 UI访问地址：http://localhost:80/swagger-ui.html
knife4j访问地址：http://localhost:80/doc.html
这里我自己改了端口号为80

就可以访问。

如果你也使用了shiro框架，就需要放行swagger2和knife4j的UI资源。
我的配置是

     //swagger。。。
            this.put("/swagger-ui.html", "anon");
            this.put("/swagger-resources/**", "anon");
            this.put("/v2/api-docs", "anon");
            this.put("/webjars/**", "anon");
            this.put("/doc.html","anon");