Swagger使用

一、Swagger介绍

Swagger是一个用于设计、构建、编写和使用RESTful API的工具集合。它允许您通过将API文档与API代码相结合来自动为API生成文档，从而提高了API的可读性和可用性。

二、使用教程

1.导入依赖

<!--knife4j依赖，用来操作swagger-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>knife4j-spring-boot-starter</artifactId>
   <version>3.0.2</version>
</dependency>

2.导入knife4j相关配置

@Configuration
@EnableSwagger2
@EnableKnife4j
public class WebMvcConfig extends WebMvcConfigurationSupport {
    @Override//设置静态资源映射
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("资管映射开始.........");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
    }
    @Bean
    public Docket createRestApi() {
        // 文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lx.reggie.controller"))
                .paths(PathSelectors.any())
                .build();
    }
	//描述接口文档
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("蓝朽")
                .version("1.0")
                .description("蓝朽工作室")
                .build();
    }
}

三、Swagger常用注解

1.@Api

描述API的信息，例如API名称、版本、作者等。

@Api(value = "用户管理", tags = {"用户控制"})
@RestController
@RequestMapping("/users")
public class UserController {

}

2.@ApiOperation

定义API端点的操作，例如名称、描述、请求方式、参数等。其中，value参数代表API操作名称，notes参数代表API操作描述信息。

@Api(value = "用户管理", tags = {"用户控制"})
@RestController
@RequestMapping("/users")
public class UserController {
    @ApiOperation(value = "根据用户ID查询用户信息", notes = "查询用户信息")
    @GetMapping("/{userId}")
    public User getUserById(@PathVariable Integer userId) {
        return userService.getUserById(userId);
    }
}

3.@ApiModel

描述实体模型，例如Model对象的名称、字段属性名、数据类型等。

@ApiModel(value = "用户实体类")
public class User {

    @ApiModelProperty(value = "用户ID", required = true)
    private Integer id;

    @ApiModelProperty(value = "用户名", required = true)
    private String username;

    @ApiModelProperty(value = "密码", required = true)
    private String password;

    @ApiModelProperty(value = "邮箱", required = true)
    private String email;
    // ...
}

4.@ApiModelProperty

给Model类属性添加注释描述。

@ApiModel(value = "用户实体类")
public class User {

    @ApiModelProperty(value = "用户ID", required = true)
    private Integer id;

    @ApiModelProperty(value = "用户名", required = true)
    private String username;

    @ApiModelProperty(value = "密码", required = true)
    private String password;

    @ApiModelProperty(value = "邮箱", required = true)
    private String email;

}

5.@ApiImplicitParams和 @ApiImplicitParam

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam:用在@ApilmplicitParams注解中，指定一个请求参数的各个方面

 	@ApiOperation("套餐分页查询")
    @ApiImplicitParams({
            @ApiImplicitParam(name="page",value = "页码",required = true),
            @ApiImplicitParam(name="pageSize",value = "每页显示多少数据",required = true),
            @ApiImplicitParam(name="name",value = "套餐名称",required = false),
    })
    @GetMapping("/page")//套餐分页查询
    public R<Page> page(int page,int pageSize,String name){
        //分页构造器
        Page<Setmeal> pageInfo  =new Page<>(page,pageSize);
        Page<SetmealDto> dtoPage = new Page<>();
        //条件构造器
        LambdaQueryWrapper<Setmeal> lqw = new LambdaQueryWrapper<>();
        //根据name进行like查询
        lqw.like(name!=null,Setmeal::getName,name);
        //添加排序条件，根据更新时间降序排序
        lqw.orderByDesc(Setmeal::getUpdateTime);
        setmealService.page(pageInfo, lqw);
        //对象拷贝
        BeanUtils.copyProperties(pageInfo,dtoPage,"records");
        List<Setmeal> records = pageInfo.getRecords();
        List<SetmealDto> list = records.stream().map((item)->{
            SetmealDto setmealDto = new SetmealDto();
            BeanUtils.copyProperties(item,setmealDto);
            //分类id
            Long categoryId = item.getCategoryId();
            //根据id查询分类对象
            Category category = categoryService.getById(categoryId);
            if (category != null) {
                //分类名称
                String name1 = category.getName();
                setmealDto.setCategoryName(name1);
            }
            return setmealDto;
        }).collect(Collectors.toList());
        dtoPage.setRecords(list);
        return R.success(dtoPage);
    }

6.@ApiIgnore

用于忽略不需要生成API文档的接口或参数。

@Api(value = "用户管理", tags = {"用户控制"})
@RestController
@RequestMapping("/users")
public class UserController {
    @ApiIgnore
    @GetMapping("/health")
    public String healthCheck() {
        return "OK";
    }
  
}