整合Swagger-UI

Swagger-UI

1 概述

Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。

常用注解

• @Api：用于修饰Controller类，生成Controller相关文档信息
• @ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
• @ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
• @ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息

2 整合

1. 添加依赖

<!--Swagger-UI API文档生产工具-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2. 配置

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                //.apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
                //为有@Api注解的Controller生成API文档
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ONE商城接口文档")
                .description("本文档为ONE商城后端api接口规范。")
                .contact("qingcai")
                .version("1.0")
                .build();
    }
}

3 添加Swagger注解

需要为控制器和实体类添加相关注解，参考

@Api(value = "UserController",tags = {"用户管理"})
@RestController
@Slf4j
@RequestMapping("/user")
public class UserController {
    @Autowired
    private UserService userService;

    /**
     * 登录
     */
    @ApiOperation("用户登录")
    @PostMapping("/login")
    public ResultDTO<Map<String,Object>> login(@RequestBody User param){
        log.debug("-----------------------> 登录：" + param);
        User user = userService.login(param);
        if(user != null){
            Map<String,Object> data = new HashMap<>();
            data.put("token","admin");
            return new ResultDTO<>(20000,"登录成功",data);
        }else{
            return new ResultDTO<>(20001,"用户名或密码错误",null);
        }
    }

    /**
     * 获取用户信息
     * @param token
     * @return
     */
    @ApiOperation("获取用户信息")
    @GetMapping("/info")
    public ResultDTO<Map<String,Object>> getEmpInfo(@RequestParam("token") String token){
        log.debug("-----------------------> 获取用户token：" + token);
        Map<String, Object> data = userService.getUserInfo(token);
        return  new ResultDTO<>(20000,"获取用户信息成功",data);
    }

    @ApiOperation("用户退出")
    @PostMapping("/logout")
    public ResultDTO<Map<String,Object>> logout(){
        return  new ResultDTO<>(20000,"操作成功",null);
    }

    @ApiOperation("用户列表查询")
    @PostMapping("/list/{pageNo}/{pageSize}")
    public ResultDTO<Map<String,Object>> getUserList(@RequestBody User param,@PathVariable("pageNo") Integer pageNo,@PathVariable("pageSize") Integer pageSize){
        Page<List<User>> result = userService.getUserList(param,pageNo,pageSize);
        Map<String,Object> data = new HashMap<>();
        data.put("total",result.getTotal());
        data.put("rows",result.getResult());
        return  new ResultDTO<>(20000,"查询成功",data);
    }

    @ApiOperation("新增用户")
    @PostMapping("")
    public ResultDTO<Object> addUser(@RequestBody User param){
        userService.addUser(param);
        return  new ResultDTO<>(20000,"新增成功",null);
    }

    @ApiOperation("修改用户")
    @PutMapping("")
    public ResultDTO<Object> updateUser(@RequestBody User param){
        userService.updateUser(param);
        return  new ResultDTO<>(20000,"修改成功",null);
    }

    @ApiOperation("修改用户状态")
    @PutMapping("/status/{userId}/{status}")
    public ResultDTO<Object> updateUserStatus(@PathVariable("userId") Integer userId,
                                              @PathVariable("status") Integer status){
        User param = User.builder().userId(userId).status(status).build();
        userService.updateUser(param);
        return  new ResultDTO<>(20000,"修改状态成功",null);
    }

    @ApiOperation("删除用户")
    @DeleteMapping("/{id}")
    public ResultDTO<Object> deleteUserById(@PathVariable("id") Integer id){
        userService.deleteUserById(id);
        return  new ResultDTO<>(20000,"删除成功",null);
    }

    @ApiOperation("查询用户")
    @GetMapping("/{id}")
    public ResultDTO<User> getUserById(@PathVariable("id") Integer id){
        User user = userService.getUserById(id);
        return  new ResultDTO<>(20000,"查询成功",user);
    }

    @ApiOperation("获取角色列表")
    @GetMapping("/role")
    public ResultDTO<List<Role>> getRoleList(){
        List<Role> roleList = userService.getRoleList();
        return  new ResultDTO<>(20000,"查询成功",roleList);
    }
}

@Data
@Table(name = "one_user")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @ApiModelProperty("用户id")
    private Integer userId;
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
    @ApiModelProperty("邮箱")
    private String email;
    @ApiModelProperty("电话")
    private String phone;
    @ApiModelProperty("状态")
    private Integer status;
    @ApiModelProperty("角色id")
    private Integer roleId;
    @Transient
    private Role role;
}

4 查看接口文档

需要运行项目，访问

http://localhost:9999/onemall/swagger-ui.html

还能直接测试哦，比如