springboot整合swagger3和knife4j
依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
application.yml配置
mvc:
pathmatch:
matching-strategy: ant_path_matcher ## 解决Failed to start bean ‘documentationPluginsBootstrapper‘ 问题
knife4j:
enable: true
swagger配置类
package com.example.springbooth2.config;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@EnableOpenApi//Swagger 开启生成接口文档功能
public class SwaggerConfig {
/**
* ture 启用Swagger3.0, false 禁用
*/
@Value("${knife4j.enable}")
private Boolean enable;
@Bean
Docket docket() {
return new Docket(DocumentationType.OAS_30)
//配置网站的基本信息
.apiInfo(apiInfo())
.enable(enable)
.select()
//指定接口的位置
// RequestHandlerSelectors.basePackage("com.example.springbooth2.controller") 接口的包所在路径
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger3") //接口文档标题
.description("接口文档") //接口文档描述
//作者信息
// new Contact("作者","作者URL","作者Email")
.contact(new Contact("jane", "http://www.baidu.com", "123@qq.com"))
.version("1.0")//版本
.build();
}
}
controller
package com.example.springbooth2.controller;
import com.example.springbooth2.config.ResponseResult;
import com.example.springbooth2.entity.User;
import com.example.springbooth2.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;
@Api(tags = "用户管理接口")
@RestController
@RequestMapping("/user")
public class UserController {
@Resource
private UserService userService;
@ApiOperation("添加用户")
@ApiImplicitParams({ // 参数名称
@ApiImplicitParam(name = "userId", value = "用户id"),
@ApiImplicitParam(name = "userName", value = "用户名", required = true)
})
@PostMapping("add")
public User add(User user) {
userService.addUser(user);
return user;
}
@ApiOperation("查询所有用户")
@GetMapping("list")
public ResponseResult<User> list() {
return ResponseResult.success(userService.list());
}
@GetMapping("/findOne")
public ResponseResult<User> findOne() {
return ResponseResult.success(userService.findById(1));
}
}
测试
knife4j访问地址 http://localhost:9090/doc.html
swagger访问地址 http://localhost:9090/swagger-ui/index.html
swagger常用注解说明
@Api
用在请求的类上
@Api(tags = “该类的作用进行说明”)
@ApiOperation
@ApiOperation(value=“改方法的作用”,note=“备注”)
@ApiImplicitParams
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)–> 请求参数的获取:@PathVariable
dataType:参数类型,默认String,其它值dataType=“Integer”
defaultValue:参数的默认值
多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中
@ApiImplicitParam 注解中虽然可以指定参数是必填的,但是却不能代替 @RequestParam(required = true) ,
前者的必填只是在 Swagger 框架内必填,抛弃了 Swagger ,这个限制就没用了,所以假如开发者需要指定一个参数必填, @RequestParam(required = true) 注解还是不能省略。
@ApiModel
如果参数是一个对象(例如上文的更新接口),对于参数的描述也可以放在实体类中。例如下面一段代码
@ApiModelProperty:用在属性上,描述类的属性
@ApiModel(value = "用户对象",description = "用户表")
public class User {
@Id
@ApiModelProperty(value = "id",required = true)
private int userId;
@ApiModelProperty(value = "用户名称",required = true)
private String userName;
}