SpringBoot之整合Swagger2

一、Swagger2介绍

Swagger是世界上最大的API开发工具框架，用于OpenAPI规范(OAS)，使整个API生命周期的开发，从设计和文档，到测试和部署。
Swagger从API文档中提取了手工工作，具有一系列用于生成、可视化和维护API文档的解决方案。

二、添加Swagger2依赖

我这里使用的是Gradle项目自动化构建开源工具

//swagger2 

compile("io.springfox:springfox-swagger2:${swaggerVersion}") 

compile("io.springfox:springfox-swagger-ui:${swaggerVersion}") 

三、编写Swagger2配置类

通过@Configuration注解，让Spring-boot来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2Configuration。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

private String basePackage = "com.qianye.controller";

private String title = "Spring Boot 使用 Swagger2 构建RESTful API";

private String version = "V1.0";

private String description = "API描述";

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title(title)
//版本号
.version(version)
//描述
.description(description)
.build();
}
}

四、在Controller类上和方法上添加Swagger注解

@RestController
@RequestMapping(value = "/mybatis")
//用在类上，说明该类的作用
@Api(value = "控制类")
public class PersonController {

@Resource
private PersonService personService;

@RequestMapping(value = "/addperson", method = RequestMethod.GET)
public String addPerson() {
Person person = new Person();
person.setName("千夜");
person.setAge(24);
personService.addPerson(person);
return "SUCCESS";
}

@RequestMapping(value = "/getpersonbyid/id/{id}", method = RequestMethod.GET)
//用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的
@ApiOperation(value = "根据id获取用户")
public Person getPersonById(@PathVariable(value = "id") Integer id) {
return personService.getPersonById(id);
}
}

五、其他注解

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

• paramType：参数放在哪个地方
• header 请求参数的获取：@RequestHeader
• query 请求参数的获取：@RequestParam
• path（用于restful接口）请求参数的获取：@PathVariable
• body（不常用）
• form（不常用）
• name：参数名
• dataType：参数类型
• required：参数是否必须传
• value：参数的意思
• defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

• code：数字，例如400
• message：信息，例如”请求参数没填好”
• response：抛出异常的类