SpringBoot整合Knife4j(swagger)
<spring-boot.version>2.3.2.RELEASE</spring-boot.version>
swagger和Knife4j区别
Knife4j和Swagger都是用于生成和维护API文档的工具,主要用于RESTful API的文档化。
Swagger是一种用于生成、描述、调用和可视化RESTful Web服务的开放源代码软件框架。它主要包含以下几个部分:
- Swagger UI:提供一个可视化界面,方便开发者和用户查看和测试API。
- Swagger Editor:在线编辑器,允许开发者使用Swagger规范编写API文档。
- Swagger Codegen:可以从API文档生成客户端SDK、服务器端代码和API文档。
- Swagger Hub:一个托管平台,用于存储和协作API文档。
Knife4j原名为Swagger Bootstrap UI,是基于Swagger的增强工具,特别是针对Spring Boot项目。它提供了更友好的用户界面和更多的功能,主要包括:
- 增强的UI:相比原生的Swagger UI,Knife4j提供了更丰富的界面和交互体验。
- 更好的文档组织:支持分组显示API,提供了更好的文档结构和导航。
- 附加功能:如动态参数、导出文档、模拟请求等。
SpringBoot整合Knife4j案例如下:
一、maven坐标
<!-- knife4j -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.2</version>
</dependency>
<!-- Spring Boot Starter Web -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
二、配置类
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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger的配置类
*/
@Configuration
@EnableSwagger2
public class MyKnife4jConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包路径,控制器类包
.apis(RequestHandlerSelectors.basePackage("cn.ilkibyxm.csmall.product"))
.paths(PathSelectors.any())
.build();
}
//构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("Spring Boot 集成 knife4 测试接口文档")
//创建人
.contact(new Contact("嗨嗨嗨!", "http://www.baidu.com", "@qq.com"))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
三、pojo
package cn.ilkibyxm.csmall.product.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.AllArgsConstructor;
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "Attribute实体类")
public class Attribute {
@ApiModelProperty(value = "属性ID,主键,自动递增", example = "1")
private Integer id;
@ApiModelProperty(value = "属性名称", example = "颜色")
private String name;
@ApiModelProperty(value = "属性描述", example = "描述属性的用途")
private String description;
}
四、controller
package cn.ilkibyxm.csmall.product.controller;
import cn.ilkibyxm.csmall.product.dao.AttributeMapper;
import cn.ilkibyxm.csmall.product.pojo.Attribute;
import cn.ilkibyxm.csmall.product.utils.ResponseWrapper;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@RestController
@RequestMapping("/attributes")
@Api(tags = "AttributeController", description = "用于属性 CRUD 操作的 API")
public class AttributeController {
@Autowired
private AttributeMapper attributeMapper;
@GetMapping("/{id}")
@ApiOperation(value = "根据ID获取属性", notes = "根据属性ID查询属性详情")
public ResponseWrapper<Attribute> getAttributeById(@PathVariable int id) {
Attribute attribute = attributeMapper.selectAttributeById(id);
if (attribute != null) {
return ResponseWrapper.success(attribute);
} else {
return ResponseWrapper.error(404, "找不到属性");
}
}
@GetMapping
@ApiOperation(value = "获取所有属性", notes = "从数据库中获取所有属性列表")
public ResponseWrapper<List<Attribute>> getAllAttributes() {
List<Attribute> attributes = attributeMapper.selectAllAttributes();
return ResponseWrapper.success(attributes);
}
@PostMapping
@ApiOperation(value = "创建属性", notes = "创建新的属性")
public ResponseWrapper<Attribute> createAttribute(@RequestBody Attribute attribute) {
int result = attributeMapper.insertAttribute(attribute);
if (result > 0) {
return ResponseWrapper.success("属性创建成功", attribute);
} else {
return ResponseWrapper.error(500, "创建属性失败");
}
}
@PutMapping("/{id}")
@ApiOperation(value = "更新属性", notes = "更新现有属性信息")
public ResponseWrapper<Attribute> updateAttribute(@PathVariable int id, @RequestBody Attribute attribute) {
attribute.setId(id);
int result = attributeMapper.updateAttribute(attribute);
if (result > 0) {
return ResponseWrapper.success("属性更新成功", attribute);
} else {
return ResponseWrapper.error(500, "更新属性失败");
}
}
@DeleteMapping("/{id}")
@ApiOperation(value = "删除属性", notes = "根据ID删除属性")
public ResponseWrapper<Void> deleteAttribute(@PathVariable int id) {
int result = attributeMapper.deleteAttribute(id);
if (result > 0) {
return ResponseWrapper.success(null);
} else {
return ResponseWrapper.error(500, "删除属性失败");
}
}
}