SpringBoot 集成 Api接口文档生成工具Swagger2
为什么使用Swagger?
随着互联网的发展,微服务逐渐流行起来,在微服务的设计下,微服务必将会有大量的接口,对于清楚的手动编写描述接口文档的话,必定是非常令人头疼抓狂,所以就选择使用Swagger来帮我们实现并解决这个问题。
Swagger的优点:
- 自动生成文档:只需要一些注解,它就可以根据代码自动生成API文档,保证了文档的时效性。
- 跨语言性,支持四十多种语言。
- Swagger UI呈现出来的是一份可交互的API文档,我们可以直接在文档页面尝试API的调用,简化了准备复杂的调用参数的过程。
- 还可以将文档规范导入相关的工具,这些工具将会为我们自动地创建自动化测试。
实现:
步骤一:在pom.xml文件中添加Swagger的依赖
<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>
步骤二:配置Swagger
@Configuration //该类为配置类
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {
@Bean
public Docket getRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.java.spb"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("基于Swagger构建的Rest API 接口文档")
.description("使用Swagger构建的Rest API文档既方便又快捷")
.contact(new Contact("一个有灵魂的程序员","https://blog.csdn.net/lz527657138","starts@163.com"))//作者信息
.version("1.0")
.build();
}
}
步骤三:Controller类添加Swagger注解
/**
* 控制层
*/
@Api(tags = "用户管理")
@RestController
public class UserInfoController {
//注入用户服务层
@Autowired
private UserService userService;
/**
* 获取用户列表
*/
@GetMapping("/getUsers")
public List<User> getUsers(Map<String, Object> queryMap){
List<User> users = userService.getUsers(queryMap);
return users;
}
/**
* 新增用户信息
*/
@ApiOperation("新增用户信息")
@PostMapping("/insert")
public String insertUser(@RequestBody User user){
Long insert = userService.insert(user);
return insert>0?"新增成功"+insert:"新增失败" + insert;
}
/**
* 根据用户id查询信息
* 传参形式使用Restful
*/
@ApiOperation(value = "根据id获取用户详细信息",notes = "使用Restful风格路径传参")
@GetMapping("/getUser/{id}")
public User getUserById(@PathVariable("id") Long id){
User userInfo = userService.getUserById(id);
return userInfo;
}
/**
* 根据id删除用户信息
*/
@ApiOperation(value = "根据id删除用户信息",notes = "使用Restful风格路径传参")
@DeleteMapping("/delete/{id}")
public String deleteById(@PathVariable("id") Long id){
boolean delete = userService.delete(id);
return delete==true?"删除成功":"删除失败";
}
}
步骤四:实体类添加Swagger注解
@Data
@NoArgsConstructor //无参构造函数
@AllArgsConstructor//有参构造(全字段)
@Accessors(chain = true)//链式; 存取器。通过该注解可以控制getter和setter方法的形式。
@ApiModel(description = "用户类")
public class User {
@ApiModelProperty(value = "id")
private Long id;//主键
@ApiModelProperty(value = "真实姓名",example = "妖怪作妖")
private String userName;//真实姓名
@ApiModelProperty(value = "登录帐号",example = "lzlz10")
private String userAccount;//登录帐号
@ApiModelProperty(value = "登录密码",example = "123123123")
private String userPassword;//登录密码
@ApiModelProperty(value = "创建时间")
private Date createTime;//创建时间
@ApiModelProperty(value = "修改时间")
private Date modifyTime;//修改时间
@ApiModelProperty(value = "手机号码",example = "18763372970")
private String telNum;//手机号码
@ApiModelProperty(value = "性别",example = "0女/1男")
private Integer gender;//性别;0:女;1:男
@ApiModelProperty(value = "生日",example = "1992-05-21")
private Date birthday;//生日
@ApiModelProperty(value = "邮箱",example = "example@163.com")
private String email;//邮箱
}
步骤五:测试看看效果 http://localhost/swagger-ui.html
如有疑问或问题,请批评指正。