SpringBoot项目添加Swagger实现自动生成API文档+（swagger-bootstrap-ui）文档界面优化+找不到文档怎么修改

在前后端分离的开发中，后端需要给前端提供API接口文档，这是非常重要的一步。但是，接口文档的编写以及更新也是在开发过程中需要耗费很多的时间，特别是一些参数的内容，容易因为错误的编写而导致前端人员使用不了接口。Swagger便是为了解决这个问题而生的，在开发的过程中，根据后端开发人员配置的参数，自动生成API文档，本篇文章就是关于在Springboot项目中使用这个插件的基础功能介绍。

一、Swagger相关注解

注解	介绍
@Api	@Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源
@ApiParam	用于 Controller 中方法的参数说明
@@ApiOperation	用在 Controller 里的方法上，说明方法的作用，每一个接口的定义
@ApiImplicitParam 和@ApiImplicitParams	用于方法上，为单独的请求参数进行说明
@ApiModel	用于字段，表示对 model 属性的说明
@ApiModelProperty	表示对类进行说明，用于实体类中的参数接收说明
@ApiResponse 和@ApiResponses	@ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse

这里主要做一个简单的介绍，具体的看下面在springboot项目具体的使用。

二、在springboot项目中的实际应用
（一）引依赖

<!--Swagger依赖-->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.9.2</version>
	</dependency>
	<!--Swagger UI依赖-->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.9.2</version>
	</dependency>

这里引入的两个依赖，第一个引入的是swagger的依赖，引入这个依赖后，可以查看到返回的json文档，非常繁琐复杂，可读性极差，这时候就需要一个展示UI，引入后者就是是一个swagger展示UI的依赖。
（二）配置swagger

@Configuration
@EnableSwagger2
@ComponentScan(basePackages = { "com.example.api.controller" })
public class SwaggerConfig {
    @Bean
    public Docket buildDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo buildApiInf(){
        return new ApiInfoBuilder()
                //页面标题
                .title("秒杀商城API文档")
                //描述
                .description("简单优雅的restful风格")
                //创建人信息
                .contact(new Contact("Curry-Kun","127.0.0.1:8080/","[email protected]"))
                .termsOfServiceUrl("")
                //版本号
                .version("1.0")
                .build();
    }
}

（三）配置接口类和实体类
1.controller层

@RestController
@RequestMapping("/miaosha")
@Api(tags = "秒杀功能模块API")
public class MiaoshaAPIController {

    @Autowired
    ProductService productService;

    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNo",value = "页码数",required = true,dataType = "int",paramType = "query"),
            @ApiImplicitParam(name = "pageSize",value = "展示条数",required = true,dataType = "int",paramType = "query")
    })

    /**
     * 商品列表页api
     * @request
     * pageNo
     * pageSize
     * @response
     * success
     * fail
     *
     * */
    @ApiOperation(value = "查询系统秒杀商品列表",notes = "采取分页的形式展示，需要pageNo页码数和pageSize每页展示条数")
    @PostMapping(value = "product_list_api")
    public ResponseResult product_list_api(@RequestParam(value = "pageNo",defaultValue = "1")int pageNo,
                                           @RequestParam(value = "pageSize",defaultValue = "6")int pageSize,
                                           User user){
        if(user == null){
            return ResponseResult.error(ResponseCode.NO_LOGIN);
        }
        PageInfo<ProductVo> page = productService.listProcuctVo(pageNo,pageSize);
        return ResponseResult.success(page);
    }

这里涉及到@Api、@ApiImplicitParams、 @ApiImplicitParam、 @ApiOperation这几个注解的使用，从上面代码中可以更加具体的看出他们各自的作用。
以为返回的结果都是封装在ResponseResult中，所以对它也需要进行注释

@Data
@ApiModel
public class ResponseResult<T> {
    @ApiModelProperty(value = "返回状态码")
    private int code;
    @ApiModelProperty(value = "返回信息")
    private String msg;
    @ApiModelProperty(value = "返回数据")
    private T data;
    /**
     * 不同的data数据类型对应不同的ResponseResult的类型
     * */

    /**
     *return code message data 方法构造器
     * */
    public ResponseResult(ResponseCode rc,T data) {
        this.data = data;
        this.msg = rc.msg;
        this.code = rc.id;
    }
    /**
     * return code message
     * */
    public ResponseResult(ResponseCode rc) {
        this.msg = rc.msg;
        this.code = rc.id;
    }
    /**
     * success
     * */
    public static <T> ResponseResult<T> success(T data){
        return new ResponseResult<T>(ResponseCode.SERVER_SUCCESS,data);
    }
    /**
     * error
     * */
    public static  <T> ResponseResult<T> error(ResponseCode rc){
        return new ResponseResult<T>(rc);
    }
}

这里涉及@ApiModel、@ApiModelProperty注解的使用。
启动项目，访问http://{ip}:{端口}/swagger-ui.html#/

（四）优化UI
上面这个UI在使用中还是不是很方便，还可以做一个更加人性化的页面，使用swagger-bootstrap-ui
1.引入依赖

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

这时候就需要访问http://{ip}:{端口}/doc.html

同时支持在线调试，只要你编写的注解足够详细，小白也能看得懂。

三、找不到生成的API文档页面怎么办？
1.出现页面无法访问错误:No mapping for GET /swagger-ui.html
这种情况的出现是系统将请求的swagger-ui.html当成了参数进行传递，这样肯定会出错。这个时候就需要修改WebMvcConfigurer，拦截swagger-ui.html，并配置文件位置。

@Configuration
public class WebConfig implements WebMvcConfigurer{

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html")//swagger-ui.html
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");

    }
}

2.访问之后出现空白页
出现这种情况，一定要确认swagger使用的UI依赖是否引入正常，很可能是依赖没有引进去，造成找不到swagger-ui.html文件，去dom.xml中追踪一下或者在查看系统依赖，如果确认没有需要的UI依赖，可以将依赖降级使用。