Spring Boot整合Swagger3.0及Knife4j
一、什么是 Swagger
Swagger是一组围绕 OpenAPI 规范构建的开源工具，可帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具包括：
-
Swagger Editor – 基于浏览器的编辑器，您可以在其中编写 OpenAPI 规范。
-
Swagger UI – 将 OpenAPI规范呈现为交互式 API 文档。
-
swagger2于17年停止维护，现在最新的版本为 Swagger3（Open Api3）。
二、什么是knife4j
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!
三、依赖引入
io.springfox
springfox-boot-starter
3.0.0
io.springfox
springfox-boot-starter
3.0.3
com.github.xiaoymin
swagger-bootstrap-ui
1.8.5
四：详细例子
配置文件加上@EnableOpenApi、@Configuration 会自动开启配置，启动类不需要加任何注解
@EnableOpenApi//该注解是Springfox-swagger框架提供的使用Swagger注解，该注解必须加
@EnableKnife4j//该注解是knife4j提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,如果你想使用这些增强功能就必须加该注解，否则可以不用加
@Configuration
public class SwaggerConfig {
/**
* 接口构建器
*
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
//用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
//设置哪些接口暴露给Swagger展示
.select()
// (第一种方式)扫描所有有注解的api，用这种方式更灵活
.apis( RequestHandlerSelectors.withMethodAnnotation( ApiOperation.class ) )
// (第二种方式)扫描指定包中的swagger注解
.apis(RequestHandlerSelectors.basePackage("com.swagger_knife4j.swagger4j.controller"))//构建API
// (第三种方式)扫描所有
.apis(RequestHandlerSelectors.any())
.paths( PathSelectors.any() )
.paths(PathSelectors.any())
.build()
.groupName("XimenesChen")
.enable(true);
}
/**
* 添加摘要信息
* 创建该API的基本信息（这些基本信息会展现在文档页面中）
* 访问地址：http://项目实际地址/swagger-ui.html
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("整合knife-4j，swaggerui基本注解")//标题
.description("整合knife-4j，swaggerui基本注解-描述")//描述
.contact(new Contact("cxm", "https://mp.csdn.net/mp_blog/manage/article?spm=1001.2014.3001.5114", "[email protected]"))
.version("V2.05")
.build();
}
}
实体类
@AllArgsConstructor
@NoArgsConstructor
@Builder
@Data
@ApiModel("common-result")
public class Result {
@ApiModelProperty(value = "返回状态码")
private Integer code;
@ApiModelProperty(value = "返回信息")
private String message;
@ApiModelProperty(value = "返回实体信息")
private T data;
}
控制器：
@Api(tags = "技术学习规划表-控制器")//@Api：用在类上，说明该类的作用
@RestController
@RequestMapping("/skillStudyPlan")
public class SkillStudyPlanController {
@ApiOperation("插入技术学习规划")//@ApiOperation：注解来给API增加方法说明
@PostMapping("insertPlan")
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功",response = Result.class),
@ApiResponse(code = 400, message = "404错误",response = Result.class),
@ApiResponse(code = 404, message = "路径不存在",response = Result.class)
})
public Result insertPlan(@ApiParam @RequestBody(required = false) SkillStudyPlanDTO skillStudyPlanDTO) {
ResponseB build = ResponseB.builder().message("ss").code(200).data("data").build();
System.out.println(skillStudyPlanDTO);
return new Result<>(200,"ok",build);
}
@ApiOperation("查询所有技术学习规划")
@GetMapping("selectAll")
public String selectAll(@RequestParam String name,@RequestParam(required = false) Integer age) {
System.out.print(name);
System.out.print(age);
return "success";
}
@PostMapping("pageHelp")
@ApiOperation(value = "分页获取标签列表")
@ApiImplicitParams({
@ApiImplicitParam(name="pageNo",value="请求页数",required = false,dataType="Integer",paramType="query"
),
@ApiImplicitParam(name="pageSize",value="请求页大小",required = false,dataType="Integer",paramType="query"),
})
//header：请求头
//query：?param=value的形式
//path：路径，Restful风格接口
//body：请求体
//form：以form表单的形式提交
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功",response = Result.class),
@ApiResponse(code = 400, message = "请求参数没填好",response = Result.class),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对",response = Result.class)
})
public Result pageHelp(@RequestParam Integer pageNo, @RequestParam Integer pageSize){
ResponseA build = ResponseA.builder().message("ss").code(200).data("data").build();
return new Result<>(200,"ok",build);
}
}
五：Swagger注解详解
就那几个，常用的注解，上边例子都有，特殊需求再网上再扒拉吧