SpringBoot [ 5.集成Swagger-Bootstrap-UI]

SpringBoot [ 5.集成Swagger-Bootstrap-UI] - 目录

---

首先Swagger它是一个API文档工具，可以通过各种注解生成接口文档，Model文档，但是我在使用Swagger的时候，觉得实用性并不高，一个机会接触到了基于Swagger开发的Swagger-Bootstrap-UI，觉得很好用;

这款工具对我们公司的开发帮助还挺大，我们后端人员经常要与前端，app的人员进行接口调试，之前都是使用一个txt或者一个word作为接口的说明于前端人员进行调试，很不方便，因为其实公司的项目大多周期短，很急，需求也是瞬息万变，根本就没有时间去维护这个文档，一定的程度上也降低了工作的效率。

这个时候，就很有必要去使用Swagger-Bootstrap-UI了，用起来不麻烦，加几个常用的注解，就可以提高工作的效率.

1.引入依赖

查看依赖版本请至文章末尾获取源码

  
  
      io.springfox
      springfox-swagger2
      ${springfox-swagger2.version}
      
      
          
              io.swagger
              swagger-models
          
      
  
  
  
      io.swagger
      swagger-models
      ${swagger.models.version}
  
  
  
      com.github.xiaoymin
      swagger-bootstrap-ui
      ${swagger-bootstrap-ui.version}
  

2.配置类

SwaggerConfiguration 类，其实这个类得配置，是有很多东西可以配置，但是我这里得话按照官方文档只配置了标题，详情，访问地址，版本。

package com.mantou.boot.config.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2Config配置类
 * @author mantou
 */
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //API 路径
                .apis(RequestHandlerSelectors.basePackage("com.mantou.boot"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //标题
                .title("swagger-bootstrap-ui RESTful APIs")
                //详情
                .description("swagger-bootstrap-ui")
                //访问地址
                .termsOfServiceUrl("http://localhost:8888/")
                //版本
                .version("1.0")
                .build();
    }
}

SwaggerWebMvcConfigurer 类

package com.mantou.boot.config.swagger;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * SpringBoot中访问doc.html报404的解决办法
 * @author mantou
 */
@Configuration
public class SwaggerWebMvcConfigurer implements WebMvcConfigurer {

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

配置好后，将项目启动，访问
http://localhost:8888/m-boot/doc.html

如下图，即成功:

3.常用注解

swagger得注解其实有很多，但是没必要每一个都去掌握，掌握几个最实用得注解就好了，其他得注解可以在学习或者工作得过程中去了解，我们可以打开它得引入得jar大概得了解一下，让自己心里有个数:

3.1.Api类注解

3.1.1.@Api

@Api顾名思义，它就是打在接口(controller类)上的注解。

@Api(tags = "用户管理")

3.1.2.@ApiOperation

@ApiOperation这个注解，打在接口里得方法上，与@Api注解结合使用

@ApiOperation(value = "新增用户")

如果你不希望某个接口通过这个文档暴露出去，可以这样

@ApiOperation(value = "批量新增用户", hidden = true)

3.2.Model类注解

Model类得注解主要是使用在一些entity，dto，vo，model上，可以在swagger-bootstrap-UI里得swagger-models里查看，可以在接口里的请求实例或者响应示例里查看

3.2.1.@ApiModel

@ApiModel(value="SysUser对象")

3.2.2.@ApiModelProperty

这个注解用来打在entity，vo …这些类得字段上，与@ApiModel注解配合使用，
说到字段，肯定有人会想，一个类的字段万一很多，有七八十个怎么办，其实这个完全不用担心，因为Mybatis-Plus的逆向工程支持生成swagger注解，详细一点的我下篇博客会介绍到

@ApiModelProperty(value = "主键:用户ID")

如果你不希望某个字段通过这个文档暴露出去，你可以这样

@ApiModelProperty(value = "用户登录密码", hidden = true)

3.3.参数类注解

其实参数类注解之前我也没有用过，这个时候我们可以看一下是哪个注解，首先打开jar，找一下:

我们来找一下名字，这个时候，一个好的命名规范就显得尤为重要了，顾名思义，很明显@ApiParam就是参数的注解，接下来我们再来看一下这个注解的内容。

看到注解里面的内容，这个注解要怎么用，我基本上已经清楚了，
我们可以猜一下这些字段，这个name应该就是参数的名称含义了，这个defaultValue和required在@RequestParam注解里都有，它们意思分别是默认值和是否必填，我们再看hidden和readOnly，一个是隐藏嘛，另一个就是只读，最后我们看一下example，这个应该是参数的填写示例，其他的字段我感觉必要性不是很高，就不看了，至于猜的对不对，下面我们可以实验一下。

3.3.1.@ApiParam

我试了一下八九不离十，只不过要注意的地方是，这个name他是参数名，所以这个应该是不需要使用，value才是参数的含义，然后这个example的确是示例值，只不过这个示例值与value不能同时使用，因为它们显示的地方是一个。

@ApiParam(name = "userId", value = "用户ID", required = true, example = "1") @RequestParam(required = false) Long userId

然后我们再来看一下hidden属性，加上这个后文档中的这个参数就消失了.

@ApiParam(name = "userId", value = "用户ID", required = true, example = "1", hidden = true

总而言之在项目当中按下面的这个示例来，就已经满足项目的需求了

//如果参数为非必填，可将required 去掉
@ApiParam(value = "XXX", required = true)

4.接口调试

接口调试的话，打开接口文档，找到调试，填写参数，点击发送即可

5.集成SpringCloud 网关

swagger-bootstrap-ui还有一个很好的功能就是，可以集成SpringCloud的网关zuul和gateway，形成一个聚合文档，通过网关配置的路由，就可以查看访问各个微服务的接口

集成zuul的文档在官方文档上有
官方文档: https://doc.xiaominfo.com/

博客源码:
https://github.com/ChinaYinMan/mantou-boot.git