SpringBoot-集成swagger2
在工作中，一个Web管理系统通常都是前后端分离的。有专门的前端开发，也有专门的后端开发，甚至有些项目可能还会要求有专门的接口开发，这类人通常就只是定义接口规范，然后由后端开发实现。那么问题来了，当一个项目需要这么多人协助完成时，我们就必须有统一的文档来约定一些规范。
对于一个接口来说，我们要定义请求方法，请求参数，参数的属性（如是否允许为空），响应体以及响应码的含义等等。传统的做法就是我们新建一个word文档，然后由接口开发去维护这份文档，然后同步到前端开发。这样的做法往往有几个痛点：（1）文档更新交流不及时导致老调试不通，工作效率低下；（2）不能直接在线测试接口，通常需要使用其他工具，比如postman；（3）文档不好管理，有时候找这东西比解决问题的时间还长。
针对以上问题，Swagger就很好解决了我们接口文档的问题。当然个人觉得就接口规范这一块，Swagger相对于Word文档是有优势的，但是其也有缺点，最明显的就是需要将这些东西都嵌入到代码中，导致程序可读性稍稍降低。那不管怎样，我们还是有必要了解一下SpringBoot如何集成Swagger的。
一、添加依赖
io.springfox
springfox-swagger2
2.6.1
io.springfox
springfox-swagger-ui
2.6.1
二、添加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 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