一、前言
由于目前工作项目写的接口越来越多了，为了能够更加方便地优化接口，以及整理接口文档，所以就考虑引入接口文档生成工具。目前的接口文档生成工具被提及较多的是Swagger，经过了引入尝试后，Swagger是比较轻松地就被引入了。但是Swagger页面属实是难以恭维，比较简单但是不美观。于是经过我再一轮的技术调研后，我发现了一个国产的技术框架——Knife4j，Knife4j是结合了Swagger，并在此基础上更精致了页面的一项技术。接下来我将以springboot2和3的环境中分别介绍，讲述如何在Springboot中引入Knife4j。
二、基于Springboot2
- maven依赖引入
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<!--在引用时请在maven中央仓库搜索最新版本号-->
<version>3.0.3</version>
</dependency>
- 在启动类上加注解@EnableOpenApi
@EnableOpenApi
@SpringBootApplication
@MapperScan("com.example.mapper")
public class DemoApplication {
public static void main(String[] args) {
//SpringApplication.run(DemoApplication.class, args);
new SpringApplicationBuilder(DemoApplication.class).run(args);
}
}
- 编写配置类
@Configuration
@EnableSwagger2
//下面两条是Knife4j引入的，若是只用Swagger可去掉
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
/**
* Swagger配置 for Knife4j
* @return
*/
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
Docket docket=new Docket(DocumentationType.SWAGGER_2)
.apiInfo(
new ApiInfoBuilder()
// 文档标题
.title("title")
// 文档描述信息
.description("content")
.contact(new Contact("peng_YunJun","https://blog.csdn.net/peng_YuJun?type=blog","pengyujun53@163.com"))
// 文档版本号
.version("1.0")
.build()
)
//分组名称
.groupName("Swagger在线文档")
// select()：生成 API 文档的选择器，用于指定要生成哪些 API 文档
.select()
//这里指定Controller扫描包路径
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
// paths()：指定要生成哪个 URL 匹配模式下的 API 文档。这里使用 PathSelectors.any()，表示生成所有的 API 文档。
.paths(PathSelectors.any())
.build();
return docket;
}
}
- 常用注解
@APi：用在请求的类上，例如Controller，表示对类的说明
@ApiOperation：用在请求的方法上，说明方法的用途、作用
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApilmplicitParams注解中，指定请求参数的各个方法
@ApiParam：用在请求的类的形参上
@ApiModel：用在类上，通常是实体类，表示一个返回响应数据的信息
@ApiModelProperty：用在属性上，描述响应类的属性
- 使用例子
@RestController
@RequestMapping("appointment")
@Api(tags = "Appointment信息请求类")
public class AppointmentController {
/**
* 服务对象
*/
@Resource
private AppointmentService appointmentService;
/**
* 分页查询
* @param currentPage
* @param pageSize
* @param appointment 筛选条件
* @return 查询结果
*/
@ApiOperation(value = "分页查询" notes = "额外说明")
@GetMapping("getPage")
public ResponseData getPage(Integer currentPage, Integer pageSize, Appointment appointment) {
if (currentPage == null || pageSize == null){
return new ResponseData(HttpStatusEnum.BAD_REQUEST.getCode(), HttpStatusEnum.BAD_REQUEST.getMessage());
}
return appointmentService.getByPage(currentPage, pageSize, appointment);
}
/**
* 通过主键查询单条数据
*
* @param id 主键
* @return 单条数据
*/
@ApiOperation("根据ID查询信息")
@GetMapping("findById")
public ResponseData findById(Long id) {
if (id == null){
return new ResponseData(HttpStatusEnum.BAD_REQUEST.getCode(),HttpStatusEnum.BAD_REQUEST.getMessage());
}
return appointmentService.findById(id);
}
}
@ApiModel(value = "ResponseDate",description = "统一前端响应格式")
public final class ResponseData<T> {
@ApiModelProperty(name = "code",value = "响应代码", example = "200")
private Integer code;
@ApiModelProperty(name = "msg",value = "响应信息",example = "添加成功")
private String msg;
@ApiModelProperty(name = "data",value = "响应数据",example = "响应数据/空")
private T data;
}
- 运行
启动服务，工程启动起来，访问http://localhost:{该服务的端口号}/doc.html查看接口信息和进行测试
三、基于Springboot3
- maven依赖引入
<!-- 集成了swagger的文档网页自动生成工具 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>
- 编写配置类
/** 接口文档生成配置
* 可以通过 /doc.html 访问接口文档
*/
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("xxx平台-API接口文档")
//描叙
.description("这是基于Knife4j OpenApi3的接口文档")
//版本
.version("v1.0")
//作者信息，自行设置
.contact(new Contact().name("xxx").email("xxx@xx.com").url("https://www.baidu.com"))
//设置接口文档的许可证信息
.license(new License().name("Apache 2.0").url("http://springdoc.org")))
.externalDocs(new ExternalDocumentation()
.description("xxx平台-主页")
.url("http://127.0.0.1:8080/index"));
}
}
- 常用注解
这里与springboot2使用的依赖不一样，Springfox改用Springdoc后，注解改变：
@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = “foo”, notes = “bar”) → @Operation(summary = “foo”, description = “bar”)
@ApiParam → @Parameter
@ApiResponse(code = 404, message = “foo”) → @ApiResponse(responseCode = “404”, description = “foo”)
- 使用例子
@RestController
@RequestMapping("api")
@Tag(name = "App接口请求类")
public class AppApiController {
@Resource
private UserService userService = new UserService();
@Operation(summary = "APP登录系统")
@LogAnnotation(info = "APP登录系统", logtypeid = Constants.loginLogTypeId)
@PostMapping("login")
@ResponseBody
public Map<String, Object> login(String phone_num, String password, HttpSession session) {
if (!StringUtils.hasText(phone_num) || !StringUtils.hasText(password)) {
Map<String, Object> resultMap = new HashMap<>();
resultMap.put("code", RequestResultEnum.BAD_REQUEST.getCode());
resultMap.put("msg", RequestResultEnum.BAD_REQUEST.getMessage());
return resultMap;
}
Map<String, Object> map = userService.loginAccount(phone_num, password);
return map;
}
}
@Schema(description = "用户实体")
public class User {
@Schema(description = "用户名称")
private String userName;
@Schema(description = "密码")
private String password;
@Schema(description = "邮箱")
private String email;
@Schema(description = "年龄")
private int age;
//...
}
- 运行
启动服务，工程启动起来，访问http://localhost:{该服务的端口号}/doc.html查看接口信息和进行测试
四、问题
-
若是一个实体一个属性有多个get或set方法，会发生报错。
因为Swagger无法确定用哪一个get或set方法，所以就会冲突报错。用注解@JsonProperty(“属性名”)可以解决，放置在其中一个get或set方法上，用于指定映射关系。文章来源：https://www.toymoban.com/news/detail-819144.html -
如何设置请求头函数
因为在当前项目中需要在请求头中携带一个Authorization为名的jwt作为登录验证，只有携带jwt的请求能够成功获取数据，所以在这一限制下，无法直接用Knife4j提供的调试功能进行调试。那么应该如何设置请求头呢，下面是一些配置代码。调整一下原有的Swagger配置类就可以了，之后查看调试功能，就可以看到请求头设置处会有一个参数等着你去设置的。文章来源地址https://www.toymoban.com/news/detail-819144.html
@Configuration
public class SwaggerConfig {
@Resource(name = "isLoginFilterRegistrationBean")
private FilterRegistrationBean isLoginFilterRegistrationBean;
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("安全生产综合信息管理平台-API接口文档")
//描叙
.description("这是基于Knife4j OpenApi3的接口文档")
//版本
.version("v1.0")
//作者信息，自行设置
.contact(new Contact().name("xxx").email("xxx@xx.com").url("https://www.baidu.com"))
//设置接口文档的许可证信息
.license(new License().name("Apache 2.0").url("http://springdoc.org")))
.externalDocs(new ExternalDocumentation()
.description("安全生产综合信息管理平台-主页")
.url("http://127.0.0.1:8081/Manage/index"))
// 配置全局鉴权参数-Authorize
.components(new Components()
.addSecuritySchemes(HttpHeaders.AUTHORIZATION,
new SecurityScheme()
.name(HttpHeaders.AUTHORIZATION)
.type(SecurityScheme.Type.APIKEY)
.in(SecurityScheme.In.HEADER)
.scheme("Bearer")
.bearerFormat("JWT")
));
}
/**
* 全局自定义扩展
* <p>
* 在OpenAPI规范中，Operation 是一个表示 API 端点（Endpoint）或操作的对象。
* 每个路径（Path）对象可以包含一个或多个 Operation 对象，用于描述与该路径相关联的不同 HTTP 方法（例如 GET、POST、PUT 等）。
*/
@Bean
public GlobalOpenApiCustomizer globalOpenApiCustomizer() {
//获取忽略拦截的名单
Map<String, String> initParameters = isLoginFilterRegistrationBean.getInitParameters();
String excludedUrisStr = initParameters.get("excludedUris");
String[] excludedUris = null;
if (StringUtils.hasText(excludedUrisStr)) {
excludedUris = excludedUrisStr.split(",");
}
String[] finalExcludedUris = excludedUris;
return openApi -> {
// 全局添加鉴权参数
if (openApi.getPaths() != null) {
openApi.getPaths().forEach((s, pathItem) -> {
// 定义表示变量 并验证Path 是否包含不过滤路径，若包含则不需要添加鉴权参数
boolean flag = finalExcludedUris != null && Arrays.stream(finalExcludedUris).anyMatch(s::contains);
if(!flag) { //不在忽略拦截名单上，需要拦截
// 接口添加鉴权参数
pathItem.readOperations()
.forEach(operation ->
operation.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION))
);
}
});
}
};
}
}
到了这里，关于【SpringBoot】SpringBoot引入接口文档生成工具（Swagger+Knife4j)的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！
