在开发中,我们需要测试或者提供给别人文档,测试的话我们一般需要使用postman等测试工具,文档提供只是内部人员使用,专门写一个word文档有点麻烦,而且每次修改的时候都需要发一个新的文档。
swagger就可以很好地解决上面的文档,它可以提供一个线上文档地址,每次修改后只要发布,文档就会更新。
首先添加需要的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
配置类:如果只是简单的使用我们类内部可以是空的,这个时候访问地址http://localhost:8088/swagger-ui.html页面如下
@Profile({"dev", "test")//设置什么环境提供文档,一般只开发环境(dev),测试环境(test)需要,正式环境(prod)关闭
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}
上面没有任何的描述,我们需要加一点信息,让使用的人更清楚。
@Profile({"dev"})//设置什么环境提供文档,一般只开发环境(dev),测试环境(test)需要,正式环境(prod)关闭
@Configuration
@EnableSwagger2
public class SwagerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.demo.controller"))//扫描的包路径
.paths(PathSelectors.any())//设置哪些请求加入文档
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot整合swagger在线文档")//标题
.description("测试用例")//说明
.contact(new Contact("fusheng","www.baidu.com",""))//文档联系信息
.version("1.0")//版本号
.build();
}
}
@RestController
@Api(value = "学校比赛controller", description = "学校信息操作")
public class MatchController {
@Autowired
CollegeService service;
@GetMapping(value = "/college")
@ApiOperation(value = "通过名字获取学校")
public BaseResult<CollegeDto> getCollegeByName(@RequestParam(name = "name") String name) {
CollegeDto college = service.findCollegeByName(name);
return BaseResult.success(college);
}
@GetMapping(value = "/college2")
@ApiOperation(value = "通过id获取学校")
public BaseResult<CollegeDto> getCollegeById(@ApiParam(name = "id", value = "学校id", required = true) String id) {
CollegeDto college = service.findCollegeById(id);
return BaseResult.success(college);
}
@PostMapping(value = "/college/save")
@ApiOperation("新建学校信息")
public BaseResult<String> saveCollege(@RequestBody @Valid CollegeReq req) {
service.saveCollege(req);
return BaseResult.success("success");
}
@GetMapping("/college3")
@ApiOperation("通过名字和地址查询学校")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "学校名称", paramType = "query", required = true),
@ApiImplicitParam(name = "address", value = "地址", paramType = "query")
})
public BaseResult<CollegeDto> getCollege(String name, String address) {
CollegeDto college = service.findByNameAndTime(name, address);
return BaseResult.success(college);
}
@GetMapping("/college/team")
@ApiOperation("通过名字查询学校及其队伍信息")
public BaseResult<CollegeTeamDto> getCollegeTeam(@RequestParam(name = "name") String name) {
CollegeTeamDto dto = service.findCollegeTeam(name);
return BaseResult.success(dto);
}
}
@Api:用在类上,对类做一个说明。
@ApiOperation:用于方法,解释这个方法的作用。
@ApiParam:可以用于参数或者方法上,用于参数上类似@RequestParam,不过name表示请求的参数,value是说明,required默认是false,和@RequestParam不一致,在项目中两个最好不要混用。@ApiParam用于方法上时,虽然不报错,没有起到应有的作用 (待考究)。
@ApiImplicitParams用于多个参数时。
@ApiImplicitParam,单个参数,paramType必填,类型有
header --> :@RequestHeader
query -->:@RequestParam
path-->@PathVariable
body --> @RequestBody User user
form(不常用)
@Data
@ApiModel(description = "学校信息")
public class CollegeReq {
@NotNull
@ApiModelProperty(value = "学校名称",required = true)
private String name;
@NotNull
@ApiModelProperty(value = "学校地址",required = true)
private String address;
@ApiModelProperty("学校联系方式")
private String phone;
@ApiModelProperty("学校官网")
private String web;
@AllowValue(allowValues = {"0","1"})
@ApiModelProperty(hidden = true)
private String type;
}
@ApiModel:用于类,对实体类进行说明。
@ApiModelProperty:用于字段,对字段进行说明,hidden=true在生成swagger文档是会不显示这个字段。