SpringBoot整合Swagger2,形成接口文档
当然,首先是创建一个Spring Boot项目,加入web依赖,创建成功后,加入两个Swagger2相关的依赖,完整的依赖如下:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
Swagger2配置
Swagger2的配置也是比较容易的,在项目创建成功之后,只需要开发者自己提供一个Docket的Bean即可,如下:
@Configuration @EnableSwagger2 public class SwaggerConfig { /** * 通过 createRestApi函数来构建一个DocketBean * 函数名,可以随意命名,喜欢什么命名就什么命名 */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容 .select() .apis(RequestHandlerSelectors.basePackage("cn.com.zz.flow.controller")) .paths(PathSelectors.any()) .build(); } //构建 api文档的详细信息函数 private ApiInfo apiInfo() { return new ApiInfoBuilder() //页面标题 .title("SpringBoot整合Swagger2 构建RESTful API") //条款地址 .termsOfServiceUrl("http://despairyoke.github.io/") .version("1.0") //描述 .description("API 描述") .build(); }
如此,Swagger2就算配置成功了,非常方便。
此时启动项目,输入http://localhost:8080/swagger-ui.html,能够看到如下页面,说明已经配置成功了:
创建接口
接下来就是创建接口了,Swagger2相关的注解其实并不多,而且很容易懂,下面我来分别向小伙伴们举例说明:
@RestController @RequestMapping("/flow/user") @Api(tags= "个人收藏夹接口") public class BoxUserCollectController { @Autowired private BoxUserCollectService boxUserCollectService; @ApiOperation(value = "获取用户信息", notes = "获取用户信息") @RequestMapping(value = "/getUserAndMail", method = RequestMethod.POST) public APIResponse getUserAndMail(@RequestParam(name = "name", required = true) String name){ if(name == null || "".equals(name)){ return APIResponse.fail("姓名必填"); } List<BoxUserCollectEntity> list = boxUserCollectService.getUserMail(name); if(list != null && list.size() > 0){ return APIResponse.success(list); } return APIResponse.success("没有查询到该用户信息"); } @ApiOperation(value = "添加个人收藏用户", notes = "添加个人收藏用户") @RequestMapping(value = "/addUserList", method = RequestMethod.POST) public APIResponse addUserList(@RequestParam(name = "userCode", required = true) String userCode, @RequestBody @ApiParam(name="list",value="传入json格式",required=true) List<BoxUserCollectEntity> list){ try { boxUserCollectService.add(list,userCode); return APIResponse.success(); }catch (Exception e){ e.printStackTrace(); return APIResponse.fail("添加失败"); } } @ApiOperation(value = "查询用户收藏", notes = "收藏用户名") @RequestMapping(value = "/getUserByCode", method = RequestMethod.POST) public APIResponse getUserByCode(@RequestParam(name = "userCode", required = true) String userCode){ List<BoxUserCollectEntity> list = boxUserCollectService.getUserList(userCode); return APIResponse.success(list); }
这里边涉及到多个API,我来向小伙伴们分别说明:
@Api注解可以用来标记当前Controller的功能。
@ApiOperation注解用来标记一个方法的作用。
@ApiImplicitParam注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入。
如果有多个参数,则需要使用多个@ApiImplicitParam注解来描述,多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
需要注意的是,@ApiImplicitParam注解中虽然可以指定参数是必填的,但是却不能代替@RequestParam(required = true),前者的必填只是在Swagger2框架内必填,抛弃了Swagger2,这个限制就没用了,所以假如开发者需要指定一个参数必填,@RequestParam(required = true)注解还是不能省略。
如果参数是一个对象(例如上文的更新接口),对于参数的描述也可以放在实体类中。例如下面一段代码:
@Data @ApiModel("收藏用户类") public class BoxUserCollectEntity extends Page implements Serializable { private static final long serialVersionUID = 1L; /** * id */ @ApiModelProperty(value = "用户id") private String id; /** * 收藏用户名称 */ @ApiModelProperty(value = "收藏用户名") private String userCode; /** * 被收藏用户名称 */ @ApiModelProperty(value = "被收藏用户名", required = true) private String nameDisplay; /** * 被收藏地址 */ @ApiModelProperty(value = "被收藏邮箱地址", required = true) private String email; /** * 创建时间 */ @JsonFormat(timezone = "GMT+8",pattern = "yyyy-MM-dd HH:mm:ss") @ApiModelProperty(value = "创建时间") private Date createTime; /** * 状态 1 已存在 0 表示 删除 */ @ApiModelProperty(value = "状态") private String status; }
测试接口:
返回接口: