转自:
SpringBoot如何使用Swagger2构建API文档呢?
下文笔者讲述springboot中使用swagger2形成API文档的方法分享,如下所示
API文档的重要性
我们都知道API文档，可以非常直观的告诉使用者 如何使用相应的方法，那么有没有一种快捷的方法生成API文档呢？ 下文呢笔者将讲述一个springboot中生成文档的利器swagger2
实现思路：
1.引入swagger2依赖
2.springBoot启动类中加入相应的注解
3.编写相应的测试类,即可查看swagger生成的api文档
例:
Swagger2引入依赖
io.springfox
springfox-swagger2
2.2.2
io.springfox
springfox-swagger-ui
2.2.2
设置启动类及swagger配置类的设置
注意事项:
swagger配置类需和springboot处于同级或下级
/**
* 启动类
*/
@RequestMapping(value = "/")
@RestController
@SpringBootApplication
@MapperScan(basePackages = "com.zzp.dao")
@Configuration
@EnableSwagger2
public class Round1Application {
@RequestMapping(value = "/",method = RequestMethod.GET)
public String helloWorld(){
return "Hello World";
}
public static void main(String[] args) {
SpringApplication.run(Round1Application.class, args);
}
@Bean
public Docket createApi(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage("com.java265.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("API文档")
.description("API使用即参数定义")
.termsOfServiceUrl("http://www.java265.com")
.contact("java265")
.version("0.2")
.build();
}
}
当我们使用@Configuration注解后,
Spring启动时加载配置
通过@EnableSwagger2开启Swagger
apiInfo:
文档的一些基本配置信息
createApi:
用于指定扫描的包路径,然后形成文档,展示给用户
http://localhost:9090/swagger-ui.html
例:
Controller中api的写法
在Controller中，我们只需使用
@ApiOperation注解
用于注释接口的基本信息
@ApiImplicitParam注解
用于设置入參信息
@RequestMapping("/user")
@RestController
public class UserController {
@Autowired
private UserService userService;
/**
* 添加用户
* @param tel 注册手机号
* @param pwd 设置密码
*/
@ApiOperation(value = "创建用户",notes = "使用手机以及密码初始化用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "tel",value = "用户手机号",required = true,dataType = "String"),
@ApiImplicitParam(name = "pwd",value = "用户初始密码",required = true,dataType = "String")
})
@PostMapping("/createUser")
public void createUser(@RequestParam("tel") String tel, @RequestParam("pwd") String pwd){
userService.createUser(tel,pwd);
}
/**
* 添加用户2
* @param userInfo
* @Valid添加表单验证，BindingResult获取验证结果
*/
@ApiOperation(value = "创建用户V2版本",notes = "使用UserInfo对象初始化用户信息")
@ApiImplicitParam(name = "userInfo",value = "用户对象",required = true,dataType = "UserInfo")
@PostMapping("/createUser2")
public String createUser2(@Valid UserInfo userInfo, BindingResult bindingResult){
if (bindingResult.hasErrors()){
return bindingResult.getFieldError().getDefaultMessage();
}
userService.createUser(userInfo.getTel(),userInfo.getPassWord());
return "OK";
}
/**
* 更新用户信息
* @param user_id 用户ID
* @param nickName 昵称
*/
@PutMapping("/updateUser/{id}")
public void updateUser(@PathVariable("id") String user_id, @RequestParam("nickName") String nickName){
userService.updateUser(user_id,nickName);
}
/**
* 获取用户信息
* @param id 用户Id
* @return
*/
@GetMapping("/getUser/{id}")
public UserInfo getUser(@PathVariable("id") Integer id){
return userService.getUser(id);
}
/**
* 删除用户
* @param id
*/
@DeleteMapping("/deleteUserByUserId/{id}")
public void deleteUserByUserId(@PathVariable("id") Integer id){
userService.deleteUserByUserId(id);
}
/**
* 使用@RequestBody获取参数，用map类型接收，再取出
* @param reqMap
*/
@PostMapping("/createUserByMap")
public void createUserByMap(@RequestBody Map reqMap){
String tel = reqMap.get("tel").toString();
String pwd = reqMap.get("pwd").toString();
userService.createUser(tel,pwd);
}
}
@RestController
@RequestMapping("/xml")
public class XMLController {
@Autowired
private XMLService service;
@Autowired
private ExceptionHandle handle;
/**
* 更新用户信息
* @param user_id 用户ID
* @param nickName 昵称
*/
@ApiOperation(value = "更新用户信息",notes = "更新用户昵称")
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String"),
@ApiImplicitParam(name = "nickName",value = "用户昵称",required = true,dataType = "String")
})
@PutMapping("/updateUser/{id}")
public Result updateUser(@PathVariable("id") String user_id, @RequestParam("nickName") String nickName){
Result result = ResultUtil.success();
try {
service.updateUser(user_id,nickName);
}catch (Exception e){
result = handle.exceptionGet(e);
}
return result;
}
/**
* 获取用户信息
* @param id 用户Id
* @return
*/
@ApiOperation(value = "获取用户信息",notes = "返回用户信息")
@ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "Integer",paramType = "path")
@GetMapping("/getUser/{id}")
public Result getUser(@PathVariable("id") Integer id){
Result result = ResultUtil.success();
try {
result.setData(service.getUser(id));
}catch (Exception e){
result = handle.exceptionGet(e);
}
return result;
}
/**
* 删除用户
* @param tel
*/
@ApiOperation(value = "删除用户",notes = "根据用户id删除用户")
@ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "Integer")
@DeleteMapping("/deleteUserByUserId/{tel}")
public Result deleteUserByUserId(@PathVariable("tel") String tel){
Result result = ResultUtil.success();
try {
UserInfo user = new UserInfo();
user.setTel(tel);
service.deleteUserByUserId(user);
}catch (Exception e){
result = handle.exceptionGet(e);
}
return result;
}
/**
* 使用@RequestBody获取参数，用map类型接收，再取出
* @param reqMap
*/
@ApiOperation(value = "创建用户V3版本",notes = "返回用户信息")
@ApiImplicitParam(name = "Map",value = "map集合",required = true,dataType = "Map")
@PostMapping("/createUserByMap")
public Result createUserByMap(@RequestBody Map reqMap){
Result result = ResultUtil.success();
try {
service.createUser(reqMap);
}catch (Exception e){
result = handle.exceptionGet(e);
}
return result;
}
}
Swagger2的优点
Swagger可避免接口文档的编写
直接由程序自动生成接口文档