spring boot整合swagger-bootstrap-ui

swagger-bootstrap-ui是国人基于swagger的一个增强框架，主要做了页面上的优化。

导入相关包

swagger注解Api包(dto、vo、entity中字段注释和接口注释会用到即对于微服务api中会用到)：

		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>

swagger-bootstrap-ui包：

		<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

Swagger配置类

package com.my.test.member.biz.swagger;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(apiInfo()).
                select().
                //扫描包的路径，即该包下面的类会被swagger文档识别一般就是控制器的包
                apis(RequestHandlerSelectors.basePackage("com.my.test.member.biz.controller")).
                paths(PathSelectors.any()).build()
                ;
    }


    private ApiInfo apiInfo(){
        return new ApiInfoBuilder().
                title("测试用户服务").
                termsOfServiceUrl("").
                contact(new Contact("xxx","xxx","xxx")).version("1.0").build();
    }
}

启动项目访问http://127.0.0.1:8080/doc.html：

注意一个点就是SwaggerConfig配置类需要被spring ioc托管，所以对于spring boot项目该类需要写在启动类所在包或其子包下面。

常用Api介绍：
@ApiModelProperty：一般用于entity、dto、vo中的字段注释-@ApiModelProperty(“姓名”)
@ApiModel：一般用于entity类的注释-@ApiModel(“测试身份证表”)
@Api：一般用于controller类的注释-@Api(value = “测试身份证表控制器”, tags = {“测试身份证表控制器”})
@ApiOperation：一般用于注释接口-@ApiOperation(value = “测试身份证表逻辑删除”, notes = “测试身份证表逻辑删除”)

接口上的入参和应答类型应当定义为具体的类否则swagger识别不了入参或者该接口返回数据的字段信息，不要定义为Object或者Map：

像这种swagger中该接口的入参就可以识别到TestIdcardQueryDTO中的字段和Page中的字段，响应参数也可以识别到TestIdcardEntity中的字段：

文档管理中全局参数设置可以为每个接口都设置共有的参数，比如在header中设置accessToken：

如果有遇到swagger文档中文乱码，包括通过swagger请求接口，输出的日志也是中文乱码，可以通过以下方式解决：
添加环境变量：MAVEN_OPTS 环境变量值：-Xms256m -Xmx512m -Dfile.encoding=UTF-8
添加完成后，重启服务，再次访问swagger。