knife4j入門

knife4j介紹

knife4j是為Java MVC框架集成Swagger生成Api文檔的增強解決方案,前身是swagger-bootstrap-ui,取名knife4j是希望它能像一把匕首一樣小巧,輕量,並且功能強悍!其底層是對Springfox的封裝，使用方式也和Springfox一致，只是對接口文檔UI進行了優化。

核心功能：

• 文檔說明：根據Swagger的規范說明，詳細列出接口文檔的說明，包括接口地址、類型、請求示例、請求參數、響應示例、響應參數、響應碼等信息，對該接口的使用情況一目了然。

• 在線調試：提供在線接口聯調的強大功能，自動解析當前接口參數,同時包含表單驗證，調用參數可返回接口響應內容、headers、響應時間、響應狀態碼等信息，幫助開發者在線調試。

knife4j入門案例

第一步：創建maven工程knife4j_demo並配置pom.xml文件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.2.RELEASE</version>
        <relativePath/>
    </parent>
    <groupId>cn.itcast</groupId>
    <artifactId>knife4j_demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.1</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>
</project>

第二步： 創建實體類User和Menu

package cn.itcast.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(description = "用戶實體")
public class User {
    @ApiModelProperty(value = "主鍵")
    private int id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年齡")
    private int age;
    @ApiModelProperty(value = "地址")
    private String address;
}

package cn.itcast.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(description = "菜單實體")
public class Menu {
    @ApiModelProperty(value = "主鍵")
    private int id;
    @ApiModelProperty(value = "菜單名稱")
    private String name;
}

第三步：創建UserController和MenuController

package cn.itcast.controller.user;

import cn.itcast.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/user")
@Api(tags = "用戶控制器")
public class UserController {
    @GetMapping("/getUsers")
    @ApiOperation(value = "查詢所有用戶", notes = "查詢所有用戶信息")
    public List<User> getAllUsers(){
        User user = new User();
        user.setId(100);
        user.setName("itcast");
        user.setAge(20);
        user.setAddress("bj");
        List<User> list = new ArrayList<>();
        list.add(user);
        return list;
    }

    @PostMapping("/save")
    @ApiOperation(value = "新增用戶", notes = "新增用戶信息")
    public String save(@RequestBody User user){
        return "OK";
    }

    @PutMapping("/update")
    @ApiOperation(value = "修改用戶", notes = "修改用戶信息")
    public String update(@RequestBody User user){
        return "OK";
    }

    @DeleteMapping("/delete")
    @ApiOperation(value = "刪除用戶", notes = "刪除用戶信息")
    public String delete(int id){
        return "OK";
    }

    @ApiImplicitParams({
   		@ApiImplicitParam(name = "pageNum", value = "頁碼", 
                       required = true, type = "Integer"),
    	@ApiImplicitParam(name = "pageSize", value = "每頁條數", 
                       required = true, type = "Integer"),
    })
    @ApiOperation(value = "分頁查詢用戶信息")
    @GetMapping(value = "page/{pageNum}/{pageSize}")
    public String findByPage(@PathVariable Integer pageNum,
                             @PathVariable Integer pageSize) {
        return "OK";
    }
}

package cn.itcast.controller.menu;

import cn.itcast.entity.Menu;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/menu")
@Api(tags = "菜單控制器")
public class MenuController {
    @GetMapping("/getMenus")
    @ApiOperation(value = "查詢所有菜單", notes = "查詢所有菜單信息")
    public List<Menu> getMenus(){
        Menu menu = new Menu();
        menu.setId(100);
        menu.setName("itcast");
        List<Menu> list = new ArrayList<>();
        list.add(menu);
        return list;
    }

    @PostMapping("/save")
    @ApiOperation(value = "新增菜單", notes = "新增菜單信息")
    public String save(@RequestBody Menu menu){
        return "OK";
    }

    @PutMapping("/update")
    @ApiOperation(value = "修改菜單", notes = "修改菜單信息")
    public String update(@RequestBody Menu menu){
        return "OK";
    }

    @DeleteMapping("/delete")
    @ApiOperation(value = "刪除菜單", notes = "刪除菜單信息")
    public String delete(int id){
        return "OK";
    }

    @ApiImplicitParams({
    	@ApiImplicitParam(name = "pageNum", value = "頁碼", 
                         required = true, type = "Integer"),
    	@ApiImplicitParam(name = "pageSize", value = "每頁條數", 
                         required = true, type = "Integer"),
    })
    @ApiOperation(value = "分頁查詢菜單信息")
    @GetMapping(value = "page/{pageNum}/{pageSize}")
    public String findByPage(@PathVariable Integer pageNum,
                             @PathVariable Integer pageSize) {
        return "OK";
    }
}

第四步：創建配置屬性類SwaggerProperties

package cn.itcast.config;

import lombok.*;
import org.springframework.boot.context.properties.ConfigurationProperties;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

/*
*配置屬性類，用於封裝接口文檔相關屬性，從配置文件讀取信息封裝成當前對象
*/

@Data
@ConfigurationProperties(prefix = "pinda.swagger")
public class SwaggerProperties {
    private String title = "在線文檔"; //標題
    private String group = ""; //自定義組名
    private String description = "在線文檔"; //描述
    private String version = "1.0"; //版本
    private Contact contact = new Contact(); //聯系人
    private String basePackage = "com.itheima.pinda"; //swagger會解析的包路徑
    private List<String> basePath = new ArrayList<>(); //swagger會解析的url規則
    private List<String> excludePath = new ArrayList<>();//在basePath基礎上需要排除的url規則
    private Map<String, DocketInfo> docket = new LinkedHashMap<>(); //分組文檔
	public String getGroup() {
        if (group == null || "".equals(group)) {
            return title;
        }
        return group;
    }
    @Data
    public static class DocketInfo {
        private String title = "在線文檔"; //標題
        private String group = ""; //自定義組名
        private String description = "在線文檔"; //描述
        private String version = "1.0"; //版本
        private Contact contact = new Contact(); //聯系人
        private String basePackage = ""; //swagger會解析的包路徑
        private List<String> basePath = new ArrayList<>(); //swagger會解析的url規則
        private List<String> excludePath = new ArrayList<>();//在basePath基礎上需要排除的url
        public String getGroup() {
            if (group == null || "".equals(group)) {
                return title;
            }
            return group;
        }
    }
    @Data
    public static class Contact {
        private String name = "pinda"; //聯系人
        private String url = ""; //聯系人url
        private String email = ""; //聯系人email
    }
}

第五步：創建application.yml文件

server:
  port: 7788
pinda:
  swagger:
    enabled: true #是否啟用swagger
    docket:
      user:
        title: 用戶模塊
        base-package: cn.itcast.controller.user
      menu:
        title: 菜單模塊
        base-package: cn.itcast.controller.menu

第六步：創建配置類SwaggerAutoConfiguration

package cn.itcast.config;

import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import org.springframework.beans.BeansException;
import org.springframework.beans.factory.BeanFactory;
import org.springframework.beans.factory.BeanFactoryAware;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.config.ConfigurableBeanFactory;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
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;
import java.util.ArrayList;
import java.util.LinkedList;
import java.util.List;

@Configuration
@ConditionalOnProperty(name = "pinda.swagger.enabled", havingValue = "true", 
                       matchIfMissing = true)
@EnableSwagger2
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerAutoConfiguration implements BeanFactoryAware {
    @Autowired
    SwaggerProperties swaggerProperties;
    private BeanFactory beanFactory;
    @Bean
    @ConditionalOnMissingBean
    public List<Docket> createRestApi(){
        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();

            // base-path處理
            // 當沒有配置任何path的時候，解析/**
            if (docketInfo.getBasePath().isEmpty()) {
                docketInfo.getBasePath().add("/**");
            }
            List<Predicate<String>> basePath = new ArrayList<>();
            for (String path : docketInfo.getBasePath()) {
                basePath.add(PathSelectors.ant(path));
            }

            // exclude-path處理
            List<Predicate<String>> excludePath = new ArrayList<>();
            for (String path : docketInfo.getExcludePath()) {
                excludePath.add(PathSelectors.ant(path));
            }

            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo)
                	.groupName(docketInfo.getGroup())
                    .select()
                    //為當前包路徑
                    .apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage()))
                    .paths(Predicates.and(Predicates.not(Predicates.or(excludePath)),Predicates.or(basePath)))
                    .build();
            configurableBeanFactory.registerSingleton(groupName, docket);
            docketList.add(docket);
        }
        return docketList;
    }

    //構建 api文檔的詳細信息
    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);

        // base-path處理
        // 當沒有配置任何path的時候，解析/**
        if (swaggerProperties.getBasePath().isEmpty()) {
            swaggerProperties.getBasePath().add("/**");
        }
        List<Predicate<String>> basePath = new ArrayList<>();
        for (String path : swaggerProperties.getBasePath()) {
            basePath.add(PathSelectors.ant(path));
        }

        // exclude-path處理
        List<Predicate<String>> excludePath = new ArrayList<>();
        for (String path : swaggerProperties.getExcludePath()) {
            excludePath.add(PathSelectors.ant(path));
        }

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .groupName(swaggerProperties.getGroup())
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
                .paths(Predicates.and(Predicates.not(Predicates.or(excludePath)),Predicates.or(basePath)))
                .build();
    }

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

第七步：創建啟動類SwaggerDemoApplication

package cn.itcast;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

執行啟動類main方法啟動項目，訪問地址：http://localhost:7788/doc.html

如果接口文檔不分組，我們可以修改application.yml文件：

server:
  port: 7788
pinda:
  swagger:
    enabled: true #是否啟用swagger
    title: test模塊
    base-package: cn.itcast.controller

再次訪問地址：http://localhost:7788/doc.html

可以看到所有的接口在一個分組中。