关于前后端分离项目接口文档之Springboot整合knife4的使用

1.前言
2. 步骤
- 2.1 引入依赖
- 2.2 编写配置类——Knife4jConfiguration
- 2.3 启动看效果
- 2.4 优化——使用几个主要的注解
- - 1. 用于类的
  - 2. 用于方法的
  - 3. 用于实体的
  - 4. controller 和实体代码
- 2.5 重新启动，看效果
- - 2.5.1 排序功能没有生效
  - 2.5.2 解决排序问题
  - 2.5.3 加注解后的其他效果
3. 简单测试
- 1. 傻瓜式测试--Hello 的
- 2. 傻瓜式测试--狗狗的
4. 参考官网

1.前言

还在手写接口文档吗？太慢了用集成了 swagger 的 knife4，让你事半功倍，往下看看吧，简单就几步，非常容易易上手，用过就爱不释手
当然前提是创建好了boot项目，这个不说了，直接看下面的吧

2. 步骤 2.1 引入依赖

如下：


            com.github.xiaoymin
            knife4j-spring-boot-starter
            
            3.0.3

2.2 编写配置类——Knife4jConfiguration

如下：

package com.liu.susu.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;


@Configuration
public class Knife4jConfiguration {
        @Bean(value = "defaultApi3")
        public Docket defaultApi3() {
            Docket docket=new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(new ApiInfoBuilder()
                            .title("素素宠物园API文档")
                            .description("# swagger-bootstrap-ui-demo RESTful APIs")
                            .termsOfServiceUrl("http://www.xx.com/")
//                            .contact("xx@qq.com")
                            .version("1.0")
                            .build())
                    //分组名称
                    .groupName("3.X版本")
                    .select()
                    //这里指定Controller扫描包路径
                    .apis(RequestHandlerSelectors.basePackage("com.liu.susu.controller"))
                    .paths(PathSelectors.any())
                    .build();
            return docket;
        }
}

2.3 启动看效果

上面配置好后，就可以启动项目看看了，浏览器中访问地址（注意ip和端口）：
```
http://localhost:8993/doc.html
```
看代码
看效果
可用是可用了，但只限于谁开发的后端谁认识，把这个给前端的话，会让前端崩溃，所以我们需要弄个任何人都能看得懂得文档来，继续……

2.4 优化——使用几个主要的注解 1. 用于类的

如下：

@Api(tags = "欢迎模块")--->标识这个类是swagger的资源
@ApiSupport(author = "乘风破浪",order = 1)--->添加作者，并对当前controller进行排序
@ApiIgnore--->忽略该 Controller，指不对当前类做扫描

2. 用于方法的

如下：

@ApiOperation(value = "2.向客人问好")
@ApiOperationSupport(author = "乘风破浪",order = 2)
@ApiImplicitParam(name = "name",value = "姓名",required = true)--->用于方法，表示单独的请求参数
@ApiImplicitParams--->用于方法，包含多个 @ApiImplicitParam
@ApiParam(name="name",value="姓名",required=true) String name

不一个一个介绍了，简单截图一下，一目了然

3. 用于实体的

如下：

@ApiModel("狗狗信息表")
@ApiModelProperty("狗狗姓名")

4. controller 和实体代码

controller 代码—hello

package com.liu.susu.controller;

import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.github.xiaoymin.knife4j.annotations.ApiSupport;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.apache.ibatis.annotations.Param;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;


@Api(tags = "欢迎模块")
@ApiSupport(author = "乘风破浪",order = 1)
@Controller
@RequestMapping("/hello")
public class HelloController {

    @ApiOperationSupport(author = "乘风破浪",order = 1)
    @ApiOperation(value = "1.打招呼")
    @ResponseBody
    @GetMapping("/hello")
    public String hello(){
        return "hello world!";
    }

    @ApiOperationSupport(author = "乘风破浪",order = 2)
    @ApiImplicitParam(name = "name",value = "姓名",required = true)
    @ApiOperation(value = "2.向客人问好")
    @GetMapping("/sayHi")
    @ResponseBody
    public String sayHi(@RequestParam(value = "name")String name){
        return"Hi:"+name;
    }

    @ApiOperationSupport(author = "乘风破浪",order = 3)
    @ApiOperation(value = "3.自我介绍")
    @GetMapping("/introduction")
    @ResponseBody
    public String introduction(@ApiParam(name="name",value="姓名",required=true) String name,@ApiParam(name="age",value="年龄") Integer age){
        return "My name is "+name +",and I'm "+age;
    }

}

controller 代码—dog

package com.liu.susu.controller.pet;

import com.alibaba.fastjson.JSONObject;
import com.alibaba.fastjson.serializer.SerializerFeature;
import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.github.xiaoymin.knife4j.annotations.ApiSupport;
import com.liu.susu.dao.pet.DogMapper;
import com.liu.susu.pojo.entity.DogEntity;
import com.liu.susu.service.pet.DogService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;


@Controller
@RequestMapping("/pet/dog")
@Slf4j
@Api(tags = "狗狗领养管理模块")
@ApiSupport(author = "乘风破浪",order = 2)
public class DogController {

    @Autowired
    private DogService dogService;

    @Autowired
    private DogMapper dogMapper;

    @ApiOperationSupport(author = "乘风破浪",order = 2)
    @ApiOperation(value = "查询所有的狗狗")
    @ResponseBody
    @GetMapping("/selectAllDogs")
    public String selectAllDogs(){
        return JSONObject.toJSONString(dogService.selectAllDogs(),
                SerializerFeature.WriteEnumUsingToString);
    }

    @ApiOperationSupport(author = "乘风破浪",order = 3)
    @ApiOperation(value = "根据筛选条件查询")
    @ResponseBody
    @PostMapping("/selectAllDogsByParam")
    public String selectAllDogsByParam(@RequestBody DogEntity dog){
        return JSONObject.toJSONString(dogMapper.selectAllDogsByParam(dog),
                SerializerFeature.WriteEnumUsingToString);
    }

    @ApiOperationSupport(author = "乘风破浪",order = 1)
    @ApiOperation(value = "新增狗狗信息")
    @ResponseBody
    @PostMapping("/insertDog")
    public String insertDog(@RequestBody DogEntity dog){
        dogMapper.insertDog(dog);
        return "success";
    }

}

实体代码

package com.liu.susu.pojo.entity;

import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import com.liu.susu.enums.SexEnum;
import com.liu.susu.enums.external.MyEnumDeserializer;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.AllArgsConstructor;
import lombok.NoArgsConstructor;

import java.io.Serializable;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.Date;


@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("狗狗信息表")
public class DogEntity implements Serializable {

	private static final long serialVersionUID = 2573398994739255813L;

	
	private Integer id;

	
	@ApiModelProperty("狗狗姓名")
	private String dogName;

	
	@ApiModelProperty("狗狗性别")
	@JsonDeserialize(using = MyEnumDeserializer.class)
	private SexEnum dogSex;

	
	@ApiModelProperty("狗狗年龄")
	private Integer dogAge;

	
	private String dogKind;

	
	private String dogColour;

	
	private String dogMaster;

	
	private Date dogBirth;

	
	private String adoptStatus;

	
	private LocalDate whenAdopt;

	
	private LocalDate lastVaccin;

	
	private Date createRecord;

	
	private LocalDateTime updateRecord;

}

2.5 重新启动，看效果 2.5.1 排序功能没有生效

如下：
可见，排序功能没有生效，解决如下

2.5.2 解决排序问题

开启增加功能即可：如下
```
knife4j:
  enable: true
```
重新启动，再看效果：

好了，问题解决

2.5.3 加注解后的其他效果

直接看图：
文档很详细了，真的是解放双手了

3. 简单测试 1. 傻瓜式测试–Hello 的

没啥可说的，傻瓜式操作即可，如下：

2. 傻瓜式测试–狗狗的

测试如下
效果：

4. 参考官网

https://doc.xiaominfo.com/

关于前后端分离项目接口文档之Springboot整合knife4的使用

Java相关栏目本月热门文章