SpringBoot整合Knife4j（swagger）

SpringBoot整合Knife4j（swagger）

<spring-boot.version>2.3.2.RELEASE</spring-boot.version>

swagger和Knife4j区别

Knife4j和Swagger都是用于生成和维护API文档的工具，主要用于RESTful API的文档化。

Swagger是一种用于生成、描述、调用和可视化RESTful Web服务的开放源代码软件框架。它主要包含以下几个部分：

1. Swagger UI：提供一个可视化界面，方便开发者和用户查看和测试API。
2. Swagger Editor：在线编辑器，允许开发者使用Swagger规范编写API文档。
3. Swagger Codegen：可以从API文档生成客户端SDK、服务器端代码和API文档。
4. Swagger Hub：一个托管平台，用于存储和协作API文档。

Knife4j原名为Swagger Bootstrap UI，是基于Swagger的增强工具，特别是针对Spring Boot项目。它提供了更友好的用户界面和更多的功能，主要包括：

1. 增强的UI：相比原生的Swagger UI，Knife4j提供了更丰富的界面和交互体验。
2. 更好的文档组织：支持分组显示API，提供了更好的文档结构和导航。
3. 附加功能：如动态参数、导出文档、模拟请求等。

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, "删除属性失败");
        }
    }
}