Spring Boot实战|整合Swagger2

《JavaEE开发的颠覆者: Spring Boot实战》系列读书笔记

Spring Boot整合Swagger2

---

想要做到前后端分离，维护接口文档是必不可少的。而接口总是在不断的变化之中，有变化就要去维护，幸好有一些工具可以减轻我们的工作量，Swagger2就是其中之一。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,它集接口文档和测试于一体，就类比将postman和showdoc的结合体。

开始使用

添加依赖

• 加入两个Swagger2相关的依赖：

  <dependency>
  			<groupId>io.springfox</groupId>
  			<artifactId>springfox-swagger2</artifactId>
  			<version>2.9.2</version>
  		</dependency>
  		<dependency>
  			<groupId>io.springfox</groupId>
  			<artifactId>springfox-swagger-ui</artifactId>
  			<version>2.9.2</version>
  		</dependency>
  

Swagger2配置

• 通过@EnableSwagger2注解启用Swagger2，然后配置一个DocketBean，这个Bean中，配置映射路径和要扫描的接口的位置。
  在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等。

      @Configuration
       @EnableSwagger2
       @ConditionalOnProperty(prefix = "swagger", name = "button-open", havingValue = "true")
       public class SwaggerConfig {
           /**
            * 创建获取api应用
            * @return
            */
           @Bean
           public Docket createRestApi() {
               return new Docket(DocumentationType.SWAGGER_2)
                       .select()
                       //这里采用包含注解的方式来确定要显示的接口(建议使用这种)
                       .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                       //.apis(RequestHandlerSelectors.basePackage("com.xx.controller"))   
   //这里采用包扫描的方式来确定要显示的接口
                       .paths(PathSelectors.any())
                       .build().apiInfo(new ApiInfoBuilder()
                               .title("测试swagger")
                               .description("spring boot整合swagger")
                               .build());
           }
       }

编写application.properties文件

• swagger开关的控制

  swagger.button-open = true
  

创建接口

• 使用注解

  Api(tags = "Swagger异步测试")
  @RequestMapping("async")
  @RestController
  public class AsyncTaskController {
  	
  	@Autowired
  	private AsyncTask asyncTask;
  
  	@ApiOperation(value = "测试-异步任务")
  	@RequestMapping(value = "doTask",method = RequestMethod.GET)
  	public String doTask() throws InterruptedException{
  		long currentTimeMillis = System.currentTimeMillis();
  		asyncTask.task1();
  		asyncTask.task2();
  		asyncTask.task3();
  		long currentTimeMillis1 = System.currentTimeMillis();
  		System.out.println("异步任务总耗时:"+(currentTimeMillis1-currentTimeMillis)+"ms");
  		return "success";
  		
  	}
  	}
  

• @Api注解可以用来标记当前Controller的功能。 @ApiOperation注解用来标记一个方法的作用。

• @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。

• 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。

访问：http://localhost:8080/swagger-ui.html ，可以看到如下效果：

所有的接口这里都列出来了，包括接口请求方式，接口地址以及接口的名字等，点开一个接口，可以看到如下信息：

点击右上角的Try it out，就可以进行接口测试。
点击Execute按钮，表示发送请求进行测试。测试结果会展示在下面的Response中。

---

参考
SpringBoot整合Swagger2，再也不用维护接口文档了！