Swagger 是一系列用于Restful API开发的工具,Springfox 封装/修改的Swagger UI。
常用注解
- @ApiModel:修改实体类
- @ApiModelProperty:修饰实体类的属性,当实体类是请求参数或返回结果时,直接生成相关文档信息
- @Api:修饰Controller类,生成Controller相关文档信息
- @ApiOperation:修饰Controller类中的方法,生成接口方法相关文档信息
- @ApiImplicitParam:修饰接口中的单个参数
- @ApiImplicitParams:一系列 @ApiImplicitParam 的包装器
添加依赖
<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>
SwaggerConfig
Swagger 配置,Springfox 提供了一个 Docket 对象,可以灵活的配置 Swagger 的各项属性。
可添加@Profile({"default","dev"})
,指定不同环境。
@Configuration
@EnableSwagger2
// @Profile({"default","dev"})
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("User")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.shpun.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger-test")
.version("1.0")
.build();
}
}
User 类
@ApiModel
public class User {
@ApiModelProperty("用户id")
private Integer id;
@ApiModelProperty("昵称")
private String nickname;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
@ApiModelProperty("可用,1可用,0不可用")
private Boolean enable;
// getter setter
}
UserController
@Api(tags = "用户管理", description = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {
private Map<Integer, User> userMap = new HashMap<>();
@ApiOperation("新增用户")
@PostMapping("/add")
public void add(@RequestBody User user){
userMap.put(user.getId(), user);
}
@ApiOperation("删除用户")
@ApiImplicitParams(value = {
@ApiImplicitParam(name = "id", value = "用户id", dataType = "Integer")
})
@GetMapping("/delete/{id}")
public void delete(@PathVariable("id") Integer id){
userMap.put(id, null);
}
@ApiOperation("修改用户")
@PostMapping("/update")
public void update(@RequestBody User user){
userMap.put(user.getId(), user);
}
@ApiOperation("查询用户")
@ApiImplicitParams(value = {
@ApiImplicitParam(name = "id", value = "用户id", dataType = "Integer")
})
@GetMapping("/get/{id}")
public User get(@PathVariable("id") Integer id){
return userMap.get(id);
}
}
启动 http://localhost:8080/swagger-ui.html
,在页面中可直接进行api调试
参考:
mall整合Swagger-UI实现在线API文档
在 Spring Boot 项目中使用 Swagger 文档
重新认识Swagger和Springfox