SpringBoot-集成swagger2

在工作中，一个Web管理系统通常都是前后端分离的。有专门的前端开发，也有专门的后端开发，甚至有些项目可能还会要求有专门的接口开发，这类人通常就只是定义接口规范，然后由后端开发实现。那么问题来了，当一个项目需要这么多人协助完成时，我们就必须有统一的文档来约定一些规范。

对于一个接口来说，我们要定义请求方法，请求参数，参数的属性（如是否允许为空），响应体以及响应码的含义等等。传统的做法就是我们新建一个word文档，然后由接口开发去维护这份文档，然后同步到前端开发。这样的做法往往有几个痛点：（1）文档更新交流不及时导致老调试不通，工作效率低下；（2）不能直接在线测试接口，通常需要使用其他工具，比如postman；（3）文档不好管理，有时候找这东西比解决问题的时间还长。

针对以上问题，Swagger就很好解决了我们接口文档的问题。当然个人觉得就接口规范这一块，Swagger相对于Word文档是有优势的，但是其也有缺点，最明显的就是需要将这些东西都嵌入到代码中，导致程序可读性稍稍降低。那不管怎样，我们还是有必要了解一下SpringBoot如何集成Swagger的。

一、添加依赖

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

二、添加Swagger配置类

@Configuration
public class SwaggerConfig {

  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)//
        .apiInfo(getApiInfo())//
        .select()//
        .apis(RequestHandlerSelectors.basePackage("com.study.springboot.jpa.web"))// 这里指定需要生成swagger接口的包路径，通常是controller所在的路径
        .paths(PathSelectors.any())//
        .build();
  }

  private ApiInfo getApiInfo() {
    return new ApiInfoBuilder().title("SpringBoot集成Swagger").description("简单优雅的restful风格")
        .version("1.0").build();
  }
}

三、开启Swagger

@SpringBootApplication
@EnableConfigurationProperties({
    Information.class })
@EnableSwagger2
public class SpringbootApplication {

  public static void main(String[] args) {
    SpringApplication.run(SpringbootApplication.class, args);
  }
}

四、编码

这里我们以SpringBoot-集成JPA中的例子做个改造，在StudentController上加上Api注解即可。

@Api(value = "学生管理接口")
@RestController
@RequestMapping("/student/*")
public class StudentController {

  @Autowired
  private StudentService studentService;

  @ApiOperation(value = "获取所有的学生信息", httpMethod = "GET")
  @RequestMapping("findAll")
  public List<Student> findAll() {
    return studentService.findAll();
  }

  @ApiOperation(value = "获取学生信息", notes = "根据url的id获取学生信息", httpMethod = "GET")
  @ApiImplicitParam(name = "id", value = "学生唯一标识", required = true, dataType = "Integer",
      paramType = "path")
  @RequestMapping(value = "{id}", method = RequestMethod.GET)
  public Student findById(@PathVariable("id") Integer id) {
    return studentService.findById(id);
  }

  @ApiOperation(value = "新增/更新学生信息", notes = "id为空时表示新增，否则为更新", httpMethod = "POST")
  @ApiImplicitParam(name = "entity", value = "学生实体类", required = true, dataType = "Student")
  @RequestMapping(value = "save", method = RequestMethod.POST)
  public Integer save(@RequestBody Student entity) throws Exception {
    return studentService.save(entity);
  }
}

五、测试

启动SpringBoot启动类，并通过http://localhost:8080/swagger-ui.html访问。

下面以findAll接口举例说明（整个界面的几个关键点其实很简单，这里就不多做介绍了）：

我们点Try it out!按钮，即是调接口进行测试，响应信息如下：

 六、 Swagger注解

最后，我们简单了解下Swagger注解，当然每个版本的注解可配置的属性存在一定的差异。

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数

源代码地址：https://gitee.com/chengab/SpringBoot/tree/master/springboot/src/main/java/com/study/springboot/swagger