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 结果
生成的接口文档会将配置项呈现为中文,提高可读性