目标:Spring Boot整合Swagger2
工具：IDEA–2020.1
学习目标:框架工具集成
本次学习的工程下载链接放到文本最后面
**注意：**本次项目基于springboot集成Mybatis基础之上的
整合Swagger2步骤：
- pom文件新增引用
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
- 配置Swagger2
A. 写一个配置类Swagger2 ，在类的上方加上@Configuration 注解， 表明是一个配置类，加上@EnableSwagger2 开启Swagger2 的功能。
在配置类Swagger2 中需要注入一个Docket 的Bean ， 该Bean 包含了apiInfo ，即基本API 文档的描述信息，以及包扫描的基本包名等信息。
示例代码如下：
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xmaven.controller"))
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restful风格，http://www.xmaven.cn/")
.termsOfServiceUrl("http://www.xmaven.cn/")
.version("1.0")
.build();
}
}
- 写生成文档的注解
Swagger2 通过注解来生成API 接口文档，文档信息包括接口名、请求方法、参数、返回信息等。通常’悄况下用于生成在线API 文档，以下的注解能够满足基本需求，注解及其描述如下。
口@Api ： 修饰整个类，用于描述Controller 类。
口@ApiOperation ：描述类的方法，或者说一个接口。
口@ApiParam ： 单个参数描述。
口@ApiModel ：用对象来接收参数。
口@ApiProperty ：用对象接收参数时，描述对象的一个字段。
口@ApiResponse: HTTP 响应的一个描述。
口@ApiResponses: HTTP 响应的整体描述。
口@Apilgnore ：使用该注解，表示Swagger2 忽略这个API 。
口@ApiError ： 发生错误返回的信息。
口@ApiParamlmplicit ： 一个请求参数。
口@ApiParamsimplicit ： 多个请求参数
- 创建Service层代码 代码如下：
public interface UserService { List<User> selectAll(); User selectById(Long id); void deleteById(Long id); int updateUser(User user); int addUser(User user); }
- 创建Service实现层代码 代码如下：
@Service public class UserServiceImpl implements UserService { @Autowired UserMapper userMapper; @Override public List<User> selectAll() { return this.userMapper.findAll(); } @Override public User selectById(Long id) { return userMapper.selectByPrimaryKey(id); } @Override public void deleteById(Long id) { userMapper.deleteByPrimaryKey(id); } @Override public int updateUser(User user) { return userMapper.updateByPrimaryKeySelective(user); } @Override public int addUser(User user) { return userMapper.insert(user); } }
- 创建Controller 代码如下：
通过@ApiOperation 注解描述生成在线文档的具体API 的说明，其中value 值为该接口的名称，notes 值为该接口的详细文档说明。这样就可以让Swagger2 生成在线的API 接口文档了。
如果不需要某接扣生成文挡，只市要再加@Apilgnore 注解即可。
@RestController
@RequestMapping("/user")
public class UserController {
@Autowired
UserService userService;
@ApiOperation(value = "用户列表",notes = "用户列表")
@RequestMapping(value = {""},method = RequestMethod.GET)
public List<User> getUsers(){
return userService.selectAll();
}
@ApiOperation(value = "创建用户",notes = "创建用户")
@RequestMapping(value = "",method = RequestMethod.GET)
public int postUser(@RequestBody User user){
return userService.addUser(user);
}
@ApiOperation(value = "获取用户详细信息",notes = "根据url的id来获取详细信息")
@RequestMapping(value = "/{id}",method = RequestMethod.POST)
public User getUser(@PathVariable Long id){
return userService.selectById(id);
}
@ApiOperation(value = "更新信息",notes = "根据url的id来更新指定用户信息")
@RequestMapping(value = "/{id}",method = RequestMethod.PUT)
public int putUsers(@PathVariable Long id , @RequestBody User user){
User user1 = new User();
user1.setName(user.getName());
user1.setPassword(user.getPassword());
user.setId(user.getId());
return userService.updateUser(user1);
}
@ApiOperation(value = "删除用户",notes = "删除用户")
@RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
public String deleteUsers(@PathVariable Long id ){
userService.deleteById(id);
return "success";
}
@ApiIgnore//使用该注解忽略这个API
@RequestMapping(value = "/hi",method = RequestMethod.GET)
public String jsonTest(){
return "hi you!";
}
}
- 启动服务，浏览器访问： http://localhost:8090/swagger-ui.html 查看在线API
评论区