SpringBoot集成Swagger生成在线API文档,并集成第三方UI

1.前言

今年公司开始尝试前后端分离开发,以前都是前端人员写好静态页面，后端当做模板在后台进行渲染
,或者干脆前后台都自己写，现在分离，java人员只提供RESTful的接口，页面交互由前端人员写，这样就会涉及到前后端人员的对接问题，为了提高对接效率，我们在项目中引入了Swagger生成API文档，辅助接口对接

2.Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务
可以根据后台代码上写的注释生成一个接口展示页面，同时还自带接口调试工具。
就像这样：

---

上面是swagger官方UI，感觉不是很好看，可以自己写页面。若果嫌麻烦，网上大神已经写好了，我们现在使用的是
swagger-bootstrap-ui，效果图如下：

---

感觉好看多了。
swagger-bootstrap-ui项目地址

3.SpringBoot集成swagger和swagger-bootstrap-ui

（1）Maven中加入依赖

<!--swagger2支持-->

  <dependency>

      <groupId>io.springfox</groupId>

      <artifactId>springfox-swagger2</artifactId>

      <version>${springfox.version}</version>

  </dependency>
  <!--这是官方自带的UI-->
  <dependency>

      <groupId>io.springfox</groupId>

      <artifactId>springfox-swagger-ui</artifactId>

      <version>${springfox.version}</version>

  </dependency>

  <!--第三方swagger UI-->

  <dependency>

      <groupId>com.drore.cloud</groupId>

      <artifactId>swagger-bootstrap-ui</artifactId>

      <version>1.3</version>

  </dependency>

(2) SpringBoot中配置Swagger

• 方式一:采用默认配置,再启动类上加入@EnableSwagger2注解即可

@SpringBootApplication

@EnableSwagger2

public class WebchatApplication extends SpringBootServletInitializer {

	protected static Logger logger= LoggerFactory.getLogger(WebchatApplication.class);

	public static void main(String[] args) {

		SpringApplication.run(WebchatApplication.class, args);

			logger.info("微信管理平台启动成功");

	}

}

现在可以访问：http://localhost:8080/项目地址/swagger-ui.html看效果了

• 方式二：默认配置缺少一些项目描述和权限的配置，可以采用javaConfig的方式做个性化配置

  1.新建一个配置类SwaggerConf
  2.代码如下：

/**
 * Swagger配置类
 */
@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {"com.qq.controller"})//controller包路径
public class SwaggerConfig {
    @Bean
    public Docket Api() {
        return new Docket(DocumentationType.SWAGGER_2)
//                .groupName("Pro")
//                .genericModelSubstitutes(DeferredResult.class)
//                .genericModelSubstitutes(ResponseEntity.class)
//                .useDefaultResponseMessages(false)
//                .forCodeGeneration(true)
//                .pathMapping("/")// base，最终调用接口后会和paths拼接在一起
                .select()
                .apis(getPredicate())
                .paths(PathSelectors.any())
//                .paths(or(regex("/api/.*")))//过滤的接口
                .build()
//                .securitySchemes(securitySchemes())
//                .securityContexts(securityContexts())
                .apiInfo(setInfo());
    }

    /**
     * 设置系统信息
     * @return
     */
    public ApiInfo setInfo(){
        return new ApiInfoBuilder()
                .title("<b>管理平台API接口文档</b>")//大标题
                .description("（1）方便前后端分离后，前端人员与后端人员的对接。<br/>（2）同时集成接口测试工具，方便后端测试接口<br/><span style='color:red'>（3）后端人员务必采用Swagger注解写好各接口的描述。</span>")//详细描述
                .version("1.0")//版本
                .termsOfServiceUrl("NO terms of service")
                .contact(new Contact("lyq", "http://blog.lyq3.com", "99190092@qq.com"))//作者
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }

    /**
     * 获取API过滤器
     * 指定需要生成文档的接口
     * @return
     */
    public Predicate<RequestHandler> getPredicate(){
        Predicate<RequestHandler> predicate = new Predicate<RequestHandler>(){
            public boolean apply(RequestHandler input) {
                Class<?> declaringClass = input.declaringClass();
                if (declaringClass == BasicErrorController.class)// 排除
                    return false;
                if(declaringClass.isAnnotationPresent(RestController.class)) // 被注解的类
                    return true;
                if(input.isAnnotatedWith(ResponseBody.class)) // 被注解的方法
                    return true;
                return false;
            }
        };
        return predicate;
    }


}

现在可以访问：http://localhost:8080/项目地址/swagger-ui.html看效果了

4.Swagger 注解的使用

配置完成后可以打开页面，也能看到接口，但是缺少接口的具体描述，比如：某个参数到底有什么作用，返回值代表什么的一系列描述是没有的，这就需要我们用Swagger提供的注解描述每一个接口和参数、返回值、状态码等

Swagger注解是重点，单开一篇来讲注解的使用和采坑记