Swagger 介绍与使用

1 介绍

• 使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，再通 Swagger 衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，以及在线接口调试页面等等
• 官网: https://swagger.io/
• knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案

2 SpringBoot 中的使用

1、导入knife4j的maven坐标

<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 MvcConfig extends WebMvcConfigurationSupport {

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
       
        //设置静态资源映射
        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("controller包的全引用"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("外卖")
                .version("1.0")
                .description("外卖接口文档")
                .build();
    }
}

3、设置静态资源，否则接口文档页面无法访问
第二步中已经添加了

@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    //设置静态资源映射
    registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}

4、在LogincheckFilter中设置不需要处理的请求路径

 //定义不需要处理的请求路径
String[] urls = new String[]{
    "/doc.html",
    "/webjars/**",
    "/swagger-resources",
    "/v2/api-docs"
};

5、访问
localhost:8080/doc.html

3 常用注解

@Api：用在请求的类上，例如Controller，表示对类的说明
@ApiModel：用在类上，通常是实体类，表示一个返回响应数据的信息
@ApiModelProperty：用在属性上，描述响应类的属性
@ApiOperation：用在请求的方法上，说明方法的用途、作用
@ApilmplicitParams：用在请求的方法上，表示一组参数说明
@ApilmplicitParam：用在@ApilmplicitParams注解中，指定一个请求参数的各个方面

4 例子

4.1 实体类

@Data
@ApiModel("套餐")
public class Setmeal implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty("主键")
    private Long id;

    //分类id
    @ApiModelProperty("分类id")
    private Long categoryId;

    //套餐名称
    @ApiModelProperty("套餐名称")
    private String name;
}

4.2 控制层

@RestController
@RequestMapping("/setmeal")
@Api(tags = "套餐相关接口")
public class SetmealController {
    /**
     * 新增套餐
     */
    @PostMapping
    @ApiOperation(value = "新增套餐接口")
    public R<String> save(@RequestBody SetmealDto setmealDto){
        return R.success("新增套餐成功");
    }

    /**
     * 套餐分页查询
     */
    @GetMapping("/page")
    @ApiOperation(value = "套餐分页查询接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "page",value = "页码",required = true),
            @ApiImplicitParam(name = "pageSize",value = "每页记录数",required = true),
            @ApiImplicitParam(name = "name",value = "套餐名称",required = false)
    })
    public R<Page> page(int page,int pageSize,String name){ 
        return R.success(dtoPage);
    }

    /**
     * 删除套餐
     */
    @DeleteMapping
    @ApiOperation(value = "套餐删除接口")
    public R<String> delete(@RequestParam List<Long> ids){
        return R.success("套餐数据删除成功");
    }

    /**
     * 根据条件查询套餐数据
     */
    @GetMapping("/list")
    @ApiOperation(value = "套餐条件查询接口")
    public R<List<Setmeal>> list(Setmeal setmeal){
        return R.success(list);
    }
}

4.3 结果

生成的接口文档会将配置项呈现为中文，提高可读性