在线接口调试工具-Swagger：展示API文档并进行接口测试

1）引入依赖

<!-- 引入swagger2依赖-->
<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>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

2）创建配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //支持webjars
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        //支持swagger
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        //支持doc
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }

/**
 * 创建API应用
 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
*/
   @Bean
   public Docket creatRestApi(){
   return new Docket(DocumentationType.SWAGGER_2)
           .select()
           // 配置 api扫描路径
           .apis(RequestHandlerSelectors.basePackage("com.example.mp.controller"))
           // 定义哪些路径的接口需要生成文档  any代表所有路径
           .paths(PathSelectors.any())
           .build()
      		//创建该API的基本信息（这些基本信息会展现在文档页面中）
           .apiInfo(new ApiInfoBuilder()
                        .title("mp用户管理") //文档首页标题
                        .version("1.0") // 文档版本
                        .description("基本用户管理")
                        .contact(new Contact("user", "www.user.cn", "12345678@qq.com")) // 创建者信息
                        .build());

}

3）在启动类上加注解**@EnableWebMvc**

@SpringBootApplication
@EnableWebMvc
public class MpDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(MpDemoApplication.class, args);
    }
}

4）常用注解

注解	说明
@Api	用在类上，描述Controller的作用
@ApiOperation	用在方法上，说明方法的用途、作用
@ApiParam	用在方法的参数上，描述单个形参的含义
@ApiImplicitParam	用在方法上，描述单个形参的含义，与上面相比使用范围更广
@ApiModel	用在类上，用对象来接收参数或者返回参数，描述类的含义
@ApiModelProperty	用在类的属性上，用对象来接收参数或者返回参数，描述字段的含义

5）示例

//实例类
@Data
@ApiModel(description = "用户表单实体")
public class UserFormDTO {

    @ApiModelProperty("id")
    private Long id;

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;

    @ApiModelProperty("注册手机号")
    private String phone;

    @ApiModelProperty("详细信息，JSON风格")
    private String info;

    @ApiModelProperty("账户余额")
    private Integer balance;
}

//controller层
@Api(tags = "用户管理接口")
@RestController
@RequestMapping("/users")
public class UserController {
    @Autowired
    private UserService userService;
    @ApiOperation("新增用户")
    @PostMapping
    public void add(@ApiParam("用户表单实体") @RequestBody UserFormDTO userDto){
        //转换为po
        User user = BeanUtil.copyProperties(userDto, User.class);
        userService.save(user);
    }
    @ApiOperation("删除用户")
    @DeleteMapping("/{id}")
    public void delete(@ApiParam("用户id") @PathVariable("id") Long id){
        userService.removeById(id);
    }
    @ApiOperation("根据id查询用户")
    @GetMapping("/{id}")
    public UserVO getById(@ApiParam("用户id") @PathVariable("id") Long id){
        User user = userService.getById(id);
        //转换为userVo在前端展示
        return BeanUtil.copyProperties(user, UserVO.class);
    }
    @ApiOperation("根据id批量查询")
    @GetMapping()
    public List<UserVO> getByIds(@ApiParam("用户id集合") @RequestParam("ids") List<Long> ids){
        List<User> users = userService.listByIds(ids);
        //转换为userVo在前端展示
        return BeanUtil.copyToList(users, UserVO.class);
    }
}

6）展示API文档并进行接口测试

• http://localhost:8080/doc.html
  
• http://localhost:8080/swagger-ui.html