前言
Swagger是一个规范和完整的框架,用于生成,描述,调用和可视化RESTful风格的web服务;
作用: 1、接口的文档在线自动生成; 2、功能测试;
二、Swagger2相关注解
注解 | 备注 |
---|---|
@Api | 修饰整个类上面,描述当前Controller的功能作用 |
@ApiOperation | 修饰方法,描述当前方法的作用 |
@ApiParam | 单个参数描述 |
@ApiModel | 用对象实体来作为入参 |
@ApiProperty | 用对象接实体收参数时,描述对象的一个字段 |
@ApiResponse | HTTP响应其中1个描述 |
@ApiResponses | HTTP响应整体描述 |
@ApiIgnore | 使用该注解忽略这个API |
@ApiError | 发生错误返回的信息 |
@ApiImplicitParam | 一个请求参数 |
@ApiImplicitParams | 多个请求参数 |
三、SpringBoot整合Swagger2
1、引入pom.xml
<!-- swagger-api依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2..2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、Swagger配置
@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages = {"com.cao.swagger.controller"})
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.cao.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("测试项目API接口")
.description("API接口的描述")
.termsOfServiceUrl("www.baidu.com")
.contact("秋一叶")
.version("1.0")
.build();
}
}
3、WebMvc配置
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
/**
* 配置静态访问资源
*/
public void addResourceHandlers(ResourceHandlerRegistry registry){
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
说明:
- addResourceHandler:对外暴露的访问路径
- addResourceLocations:内部文件的目录
4、UserController.java
@RestController
@Api(value = "用户模块", tags = "用户模块的接口")
public class UserController {
//模拟数据库
public static List<User> users = new ArrayList<>();
static{
users.add(new User("张三", "123456"));
users.add(new User("李四", "789456"));
}
@ApiOperation(value = "获取用户列表", notes = "获取所有用户的列表")
@GetMapping("/users")
public Object users(){
Map<String, Object> map = new HashMap<>();
map.put("users", users);
return map;
}
@ApiOperation(value = "获取单个用户", notes = "根据ID查询某个用户的信息")
@ApiImplicitParam(value = "用户的ID", paramType = "path")
@GetMapping("user/{id}")
public User getUserById(@PathVariable("id") int id){
return users.get(id);
}
@ApiOperation(value = "添加用户", notes = "根据传入的用户信息添加用户")
@ApiImplicitParam(value = "用户对象", paramType = "query")
@PostMapping("/user")
public Object add(User user){
return users.add(user);
}
@ApiOperation(value = "删除用户", notes = "根据ID删除某个用户的信息")
@ApiImplicitParam(value = "用户的ID", paramType = "path")
@GetMapping("user2/{id}")
public Object delete(@PathVariable("id") int id){
return users.remove(id);
}
}
5、效果图
地址栏输入:http://localhost:8080/swagger-ui.html