Knife4J的基本使用

knife4J是对Swagger的增强解决方案，其底层封装了SpringFox，使用方式也和SpringFox一致，但是对接口文档的UI进行了优化

1.要使用Knife4J首先要导入相应的坐标:

   <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>knife4j-spring-boot-starter</artifactId>
       <version>3.0.3</version>
   </dependency>

2.然后创建User实体类

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户实体",description = "用户实体")
public class User {
    @ApiModelProperty(value = "主键")
    private int id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
    @ApiModelProperty(value = "地址")
    private String address;
}

3.然后创建UserController控制类

@RestController
@RequestMapping("/users")
@Api(tags = "用户控制器")
public class UserController {
    @GetMapping
    @ApiOperation(value = "查询所有用户",notes = "查询所有用户信息")
    public List<User> getAllUsers(){
        User user = new User();
        user.setId(100);
        user.setName("zhang");
        user.setAge(27);
        user.setAddress("安徽省合肥市");
        List<User> users = new ArrayList<>();
        users.add(user);
        return users;
    }
    @DeleteMapping("/{id}")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "id",value = "用户编号",required = true,type = "Integer")
    )
    @ApiOperation(value = "删除用户", notes = "删除用户信息")
    public String delete(@PathVariable int id){
        return "OK";
    }
 }

4.通过项目的application.yml配置文件对knife4J的参数进行配置，可以让我们的程序进一步解耦。通过读取yml文件中的配置信息，我们可以在不修改源码的情况下对接口文档的一些参数进行调整。首先，我们要在yml文件中添加一下配置信息:

server:
  port: 9001

swagger:
  title: 测试文档标题
  base-package: cn.zlprime
  docket:
    api1:
      title: 标题1
    api2:
      title: 标题2
      version: 2.2.2.2

5.编写配置属性类读取yml文件信息并封装起来

@ConfigurationProperties(prefix = "swagger")
@Data
public class SwaggerProperties {

    private String title="knife4j接口文档";
    private String group="";
    private String version="1.1";
    private String description="这是一个UI经过优化的接口文档";
    private Contact contact = new Contact();
    private String basePackage="com.zlprime";
    private Map<String,DocketInfo> docket  = new LinkedHashMap<>();

    public String getGroup(){
        if(group!=null || "".equals(group)){
            return group;
        }
        return title;
    }

    @Data
    public static class DocketInfo{
        private String title="knife4j接口文档";
        private String group="";
        private String version="1.1";
        private String description="这是一个UI经过优化的接口文档";
        private String basePackage="com.zlprime";
        private Contact contact = new Contact();
        public String getGroup(){
            if(group!=null || "".equals(group)){
                return group;
            }
            return title;
        }
    }

    @Data
    public static class Contact{
        private String name="zlprime";
        private String url="https://www.zlprime.cn";
        private String email="zl_al@live.com";
    }
}

6.编写Knife4J的配置类

@Configuration
@EnableSwagger2  //开启Swagger2,这个注解很关键
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerAutoConfiguration implements BeanFactoryAware {

    @Autowired
    SwaggerProperties swaggerProperties;

    private BeanFactory beanFactory;

    @Bean
    @ConditionalOnMissingBean
    public List<Docket> getRestApi(){
        ConfigurableBeanFactory configurableBeanFactory =
                (ConfigurableBeanFactory) beanFactory;
        List<Docket> docketList = new LinkedList<>();
        // 没有分组
        if (swaggerProperties.getDocket().isEmpty()) {
            Docket docket = createDocket(swaggerProperties);
            configurableBeanFactory.registerSingleton(swaggerProperties.getTitle(),
                    docket);
            docketList.add(docket);
            return docketList;
        }
        // 分组创建
        for (String groupName : swaggerProperties.getDocket().keySet()){
            SwaggerProperties.DocketInfo docketInfo =
                    swaggerProperties.getDocket().get(groupName);
            ApiInfo apiInfo = new ApiInfoBuilder()
                    //页面标题
                    .title(docketInfo.getTitle())
                    //创建人
                    .contact(new Contact(docketInfo.getContact().getName(),
                            docketInfo.getContact().getUrl(),
                            docketInfo.getContact().getEmail()))
                    //版本号
                    .version(docketInfo.getVersion())
                    //描述
                    .description(docketInfo.getDescription())
                    .build();

            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo)
                    .groupName(docketInfo.getGroup())
                    .select()
                    //为当前包路径
                    .apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage()))
                    .build();
            configurableBeanFactory.registerSingleton(groupName, docket);
            docketList.add(docket);
        }
        return docketList;
    }

    private ApiInfo apiInfo(SwaggerProperties swaggerProperties) {
        return new ApiInfoBuilder()
                //页面标题
                .title(swaggerProperties.getTitle())
                //创建人
                .contact(new Contact(swaggerProperties.getContact().getName(),
                        swaggerProperties.getContact().getUrl(),
                        swaggerProperties.getContact().getEmail()))
                //版本号
                .version(swaggerProperties.getVersion())
                //描述
                .description(swaggerProperties.getDescription())
                .build();
    }

    //创建接口文档对象
    private Docket createDocket(SwaggerProperties swaggerProperties) {
        //API 基础信息
        ApiInfo apiInfo = apiInfo(swaggerProperties);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .groupName(swaggerProperties.getGroup())
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
                .build();
    }

    @Override
    public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
        this.beanFactory = beanFactory;
    }
}

7.最后创建SpringBoot的启动类，启动程序

@SpringBootApplication
public class SwaggegrApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggegrApplication.class);
    }
}

启动程序，在浏览器中输入 localhost:9001/doc.html ,即可看到knife4J生成的接口文档

最新：本方法中，配置接口分组已失效