一、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:抛出异常的类