一、导包
<!--swagger2 start-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<!--swagger2 end-->
二、配置
这一步很重要，经常是因为这里配置到了其他类里，或者单独写一个类存放而导致启动后报404错误，官网上配置是写在启动类上的。
在启动类上添加注释
@EnableSwagger2
添加bean
//swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.shrek.supervisor.controller"))
.paths(PathSelectors.any())
.build();
}
//构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("shrek系统构建RESTful API")
//创建人
.contact(new Contact("shrek", "https://blog.csdn.net/weixin_36104843", ""))
//版本号
.version("1.0")
//描述
.description("shrek_supervisor API 描述")
.build();
}
三、配置controller
这里不详解，自己百度
常用注解：
1. @Api
用在类上，说明该类的作用
@Api(value = "UserController", description = "用户相关api")
2. @ApiOperation
用在方法上，说明方法的作用
@ApiOperation(value = "查找用户", notes = "查找用户", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
3 @ApiImplicitParams
用在方法上包含一组参数说明
4. @ApiImplicitParam
用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数放在哪个地方
header–>请求参数的获取：@RequestHeader
query–>请求参数的获取：@RequestParam
path（用于restful接口）–>请求参数的获取：@PathVariable
body（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
})
5. @ApiResponses
用于表示一组响应
6. @ApiResponse
用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如”请求参数没填好”
response：抛出异常的类
@ApiResponses(value = {
@ApiResponse(code = 400, message = "No Name Provided")
})
7. @ApiModel
描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModel(value = "用户实体类")
8. @ApiModelProperty
描述一个model的属性
@ApiModelProperty(value = "登录用户")
下面是controller的案例
@RestController
@RequestMapping(value="/supervisor")
@Api("Supervisor相关的api")
public class SupervisorController {
@Autowired
SupervisorService supervisorService;
@ApiOperation(value="统计supervisor", notes="根据example统计supervisor")
@ApiImplicitParam(name = "example", value = "管理员查询实体SupervisorExample", required = true, dataType = "SupervisorExample")
@RequestMapping(value="/countByExample", method=RequestMethod.POST)
public long countByExample(@RequestBody SupervisorExample example) {
return supervisorService.countByExample(example);
}
@ApiOperation(value="选择删除supervisor", notes="根据example删除supervisor")
@ApiImplicitParam(name = "example", value = "管理员查询实体SupervisorExample", required = true, dataType = "SupervisorExample")
@RequestMapping(value="/deleteByExample", method=RequestMethod.DELETE)
public int deleteByExample(@RequestBody SupervisorExample example) {
return supervisorService.deleteByExample(example);
}
@ApiOperation(value="主键删除supervisor", notes="根据主键id删除supervisor")
@RequestMapping(value="/deleteByPrimaryKey", method=RequestMethod.DELETE)
public int deleteByPrimaryKey(@ApiParam("主键id") @RequestParam Integer id) {
return supervisorService.deleteByPrimaryKey(id);
}
@ApiOperation(value="添加supervisor", notes="利用supervisor实体进行插入")
@ApiImplicitParam(name = "record", value = "管理员实体Supervisor", required = true, dataType = "Supervisor")
@RequestMapping(value="/insert", method=RequestMethod.PUT)
public int insert(@RequestBody Supervisor record) {
return supervisorService.insert(record);
}
@ApiOperation(value="选择添加supervisor", notes="利用supervisor实体进行参数选择性的插入")
@ApiImplicitParam(name = "record", value = "管理员实体Supervisor", required = true, dataType = "Supervisor")
@RequestMapping(value="/insertSelective", method=RequestMethod.PUT)
public int insertSelective(@RequestBody Supervisor record) {
return supervisorService.insertSelective(record);
}
@ApiOperation(value="查询supervisor", notes="利用supervisorExample实体进行查询supervisor集合")
@ApiImplicitParam(name = "example", value = "管理员实体SupervisorExample", required = true, dataType = "SupervisorExample")
@RequestMapping(value="/selectByExample", method=RequestMethod.POST)
public List<Supervisor> selectByExample(@RequestBody SupervisorExample example) {
return supervisorService.selectByExample(example);
}
@ApiOperation(value="主键查询supervisor", notes="根据主键id查询supervisor")
@RequestMapping(value="selectByPrimaryKey", method=RequestMethod.POST)
public Supervisor selectByPrimaryKey(@ApiParam("主键id") @RequestParam Integer id) {
return supervisorService.selectByPrimaryKey(id);
}
@ApiOperation(value="选择信息更新管理员信息", notes="根据example筛选要更新的实体，然后用record进行信息选择性的更新")
@ApiImplicitParams({
@ApiImplicitParam(name = "record", value = "管理员实体", required = true, dataType = "Supervisor"),
@ApiImplicitParam(name = "example", value = "管理员查询实体", required = true, dataType = "SupervisorExample")
})
@RequestMapping(value="/updateByExampleSelective", method=RequestMethod.PUT)
public int updateByExampleSelective(@RequestBody Supervisor record, @RequestBody SupervisorExample example) {
return supervisorService.updateByExampleSelective(record, example);
}
@ApiOperation(value="更新管理员信息", notes="根据example筛选要更新的实体，然后用record进行信息选择性的更新")
@ApiImplicitParams({
@ApiImplicitParam(name = "record", value = "管理员实体", required = true, dataType = "Supervisor"),
@ApiImplicitParam(name = "example", value = "管理员查询实体", required = true, dataType = "SupervisorExample")
})
@RequestMapping(value="/updateByExample", method=RequestMethod.PUT)
public int updateByExample(@RequestBody Supervisor record, @RequestBody SupervisorExample example) {
return supervisorService.updateByExample(record, example);
}
@ApiOperation(value="更新supervisor", notes="根据supervisor实体进行选择性的参数更新")
@ApiImplicitParam(name = "record", value = "管理员实体Supervisor", required = true, dataType = "Supervisor")
@RequestMapping(value="/updateByPrimaryKeySelective", method=RequestMethod.PUT)
public int updateByPrimaryKeySelective(@RequestBody Supervisor record) {
return supervisorService.updateByPrimaryKeySelective(record);
}
@ApiOperation(value="更新supervisor", notes="根据supervisor实体进行更新")
@ApiImplicitParam(name = "record", value = "管理员实体Supervisor", required = true, dataType = "Supervisor")
@RequestMapping(value="/updateByPrimaryKey", method=RequestMethod.PUT)
public int updateByPrimaryKey(@RequestBody Supervisor record) {
return supervisorService.updateByPrimaryKey(record);
}
}
参考：https://blog.csdn.net/u014231523/article/details/76522486
https://www.zhihu.com/question/28119576