先后端分离后,维护接口文档基本上是必不可少的工做,swagger2能够大量的减小咱们的工做量。java
<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>
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket creatRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .pathMapping("/") .select() .apis(RequestHandlerSelectors.basePackage("org.javaboy.controller")) .paths(PathSelectors.any()) .build().apiInfo(new ApiInfoBuilder() .title("springboot整合swagger") .description("详细信息") .version("版本号") .contact(new Contact("邮箱","https://www.csdn.net/","1525702966@qq.com")) .licenseUrl("http://www.javaboy.org") .build()); } }
@ApiModel @Data public class User { @ApiModelProperty(value = "用户id") private Integer id; @ApiModelProperty(value = "用户名") private String username; @ApiModelProperty(value = "用户地址") private String address; }
@RestController @RequestMapping("/user") @Api(tags = "用户管理相关接口") public class UserController { @PostMapping("/") @ApiOperation("添加用户的接口") @ApiImplicitParams({ @ApiImplicitParam(name = "username",value = "用户名",defaultValue = "张三"), @ApiImplicitParam(name = "address",value = "用户地址",defaultValue = "安阳",required = true) }) public RespBean addUser(String username, @RequestParam(required = true) String address){ return new RespBean(); } @GetMapping("/") @ApiOperation("根据id查询用户的接口") @ApiImplicitParam(name = "id",value = "用户id",defaultValue = "99",required = true) public User getUserById(@PathVariable Integer id){ User user=new User(); user.setId(id); return user; } @PutMapping("/{id}") @ApiModelProperty("根据id更新用户的接口") public User updateUserById(@RequestBody User user){ return user; } private class RespBean { } }
@Api 注解能够用来标记当前 Controller 的功能。
@ApiOperation 注解用来标记一个方法的做用。
@ApiImplicitParam 注解用来描述一个参数,能够配置参数的中文含义,也能够给参数设置默认值,这样在接口测试的时候能够避免手动输入。
若是有多个参数,则须要使用多个 @ApiImplicitParam 注解来描述,多个 @ApiImplicitParam 注解须要放在一个 @ApiImplicitParams 注解中。
须要注意的是,@ApiImplicitParam 注解中虽然能够指定参数是必填的,可是却不能代替 @RequestParam(required = true) ,前者的必填只是在 Swagger2 框架内必填,抛弃了 Swagger2 ,这个限制就没用了,因此假如开发者须要指定一个参数必填, @RequestParam(required = true) 注解仍是不能省略。
若是参数是一个对象(例如上文的更新接口),对于参数的描述也能够放在实体类中。例以下面一段代码:git
@ApiModel public class User { @ApiModelProperty(value = "用户id") private Integer id; @ApiModelProperty(value = "用户名") private String username; @ApiModelProperty(value = "用户地址") private String address; //getter/setter }
路径名搞错了
源码地址:码云https://gitee.com/liu_jiahao_719/springboot-swagger2web