springboot + swagger2的简单使用
程序员文章站
2022-07-02 22:07:17
...
springboot + swagger2
-
创建swagger2的springboot项目
-
在pom文件里面加上如下依赖
<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> -
在项目里面创建一个config包，编写Swagger的配置类,如下图所示
SwaggerConfig配置类内容
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.select()//接口都有哪些东西
.apis(RequestHandlerSelectors.basePackage("com.apt.springmvcdemo.web.controller"))//controller在哪
.paths(PathSelectors.any())//所有的路径都生成文档
//apiInfo就是用来配置网站的基本信息的
.build().apiInfo(new ApiInfoBuilder()
.description("接口文档的描述信息")
.title("项目接口文档")
//联系人信息
.contact(new Contact("javalqg", "http:www.baidu.com", "aaa@qq.com"))
.version("v1.0")
.license("Apache2.0")
.build());
}
}
这里提供一个配置类，首先通过@EnableSwagger2注解启用Swagger2，然后配置一个Docket Bean，这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等。
如此，Swagger2就算配置成功了，非常方便。
此时启动项目，输入http://localhost:8080/swagger-ui.html，能够看到如下页面，说明已经配置成功了：
4. 创建接口
@Api(tags = "用户数据接口")
@RestController
public class UserController {
@ApiOperation(value = "查询用户",notes = "根据id查询用户")
@GetMapping("/user") //在restful风格里面要明确指出是get请求还是post请求，不然前端会收到6个方法
@ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "99")
public User getUserById(Integer id){
User user = new User();
user.setId(id);
return user;
}
@ApiOperation(value = "删除用户",notes = "根据id删除用户")
@ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "99")
@ApiResponses({
@ApiResponse(code = 200,message = "删除成功"),
@ApiResponse(code = 500,message = "删除失败")
})
@DeleteMapping("/user/{id}")
public void deleteUserById(@PathVariable Integer id){
System.out.println("deleteUserById:"+id);
}
@PutMapping("/user")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "用户id",required = true,defaultValue = "99"),
@ApiImplicitParam(name = "username",value = "用户名",required = true,defaultValue = "javalqg")
})
@ApiOperation(value = "更新用户",notes = "根据用户id更新用户名")
@ApiIgnore //生成接口时忽略它
public User updateUeernameById(String username,Integer id){
User user = new User();
user.setId(id);
user.setUsername(username);
return user;
}
@PostMapping("/user")
@ApiOperation(value = "添加用户",notes = "添加用户接口") //@RequestBody:以json的方式来传递参数
public User addUser(@RequestBody User user){
return user;
}
}
这里边涉及到多个API，我来向小伙伴们分别说明：
1. @Api注解可以用来标记当前Controller的功能。
2. @ApiOperation注解用来标记一个方法的作用。
3. @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
4. 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
5. 需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。
6. 如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。例如下面一段代码：
@ApiModel(value = "用户实体类",description = "用户信息描述类")
public class User {
@ApiModelProperty(value = "用户id")
private Integer id;
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "用户地址")
private String address;
//省略getter和getter
}
@RestController
@RequestMapping("/user")
@Api(tags = "用户管理相关接口")
public class UserController {
@Autowired
private UserService userService;
@ApiOperation("获取用户列表")
@RequestMapping(value = "/list")
public List<UserEntry> findUserList(){
return userService.findUserList();
}
@ApiOperation("新增用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "userName",value = "用户名",defaultValue = "zlf"),
@ApiImplicitParam(name="password",value = "密码",defaultValue = "zlf"),
@ApiImplicitParam(name = "email",value = "邮箱",defaultValue = "aaa@qq.com")
})
@RequestMapping(value = "/add",method = RequestMethod.GET)
public String addUser(@RequestParam(value = "userName")String uaserName,@RequestParam(value = "password")String password,@RequestParam(value = "email")String email){
int falg=userService.addUser(uaserName,password,email);
if(falg>0){
return "success";
}
return "error";
}
@ApiOperation("删除用户信息")
@ApiImplicitParam(name = "id",value = "1",defaultValue = "1")
@RequestMapping(value = "/delete",method = RequestMethod.GET)
public String deleteUser(@RequestParam(value = "id")int id){
if(userService.deleteUser(id)>0){
return "success";
}
return "error";
}
@ApiOperation("获取用户列表2")
@RequestMapping(value = "/list2",method = RequestMethod.GET)
public List<UserEntry> findUserList2(){
return userService.findUserList2();
}
@ApiOperation("新增用户信息2")
@ApiImplicitParams({
@ApiImplicitParam(name = "userName",value = "用户名",defaultValue = "zlf"),
@ApiImplicitParam(name="password",value = "密码",defaultValue = "zlf"),
@ApiImplicitParam(name = "email",value = "邮箱",defaultValue = "aaa@qq.com")
})
@RequestMapping(value = "/add2",method = RequestMethod.GET)
public String addUser2(@RequestParam(value = "userName")String uaserName,@RequestParam(value = "password")String password,@RequestParam(value = "email")String email){
int falg= userService.addUser2(uaserName,password,email);
if(falg>0){
return "success";
}
return "error";
}
@ApiOperation("删除用户信息2")
@ApiImplicitParam(name = "id",value = "1",defaultValue = "1")
@RequestMapping(value = "/delete2",method = RequestMethod.GET)
public String deleteUser2(@RequestParam(value = "id")int id){
if(userService.deleteUser2(id)>0){
return "success";
}
return "error";
}
}