knife4j+nacos 禁用调试功能+请求参数过滤

nacos注册中心聚合OpenAPI文档

整个工程的目录：

访问地址：https://github.com/WQL-Java97/doc

工程目录说明如下：

工程	说明
service-user	一个非常简单的用户服务，包含用户接口
service-order	一个非常简单的订单服务，包含订单接口
service-doc	聚合文档工程，也是一个Spring Boot工程，不过需要注意的是基于web的，而非webflux

nacos注册中心以及service-user、order等都非常简单，按照注册中心、用户服务、订单服务依次进行启动即可

此时，我们访问nacos的主页，最终能看到我们的注册中心存在两个服务，如下图：

目的： 从nacos注册中心直接进行聚合，也就是将用户服务、订单服务的OpenAPI文档聚合在一起进行展示

主要步骤如下：

1、第一步

在service-doc工程引入knife4j-aggregation-spring-boot-starter依赖

<?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 https://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.3.2.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.nucarf</groupId>
    <artifactId>service-doc</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>service-doc</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

2、第二步

配置properties配置文件，如下：

server.port=8073
knife4j.enableAggregation=true
knife4j.nacos.enable=true
knife4j.nacos.serviceUrl=http://localhost:8848/nacos/
knife4j.nacos.routes[0].name=订单服务
knife4j.nacos.routes[0].service-name=service-order
knife4j.nacos.routes[0].location=/v2/api-docs?group=default
knife4j.nacos.routes[0].service-path=/

knife4j.nacos.routes[1].name=用户模块
knife4j.nacos.routes[1].service-name=service-user
knife4j.nacos.routes[1].location=/v2/api-docs?group=default
knife4j.nacos.routes[1].service-path=/

3、第三步

启动项目，访问doc.html进行查看，效果图如下 :

注：本项目禁用了调试功能，具体配置在功能模块中。

具体实现功能模块展示：

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 https://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.3.2.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.nucarf</groupId>
    <artifactId>service-user</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>service-user</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- https://mvnrepository.com/artifact/com.alibaba.cloud/spring-cloud-starter-alibaba-nacos-discovery -->
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
            <version>2.2.1.RELEASE</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-micro-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

application.properties文件：

server.port=8072
spring.application.name=service-user
spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848

#开启knife4j增强
knife4j.enable=true
#禁用调试功能
knife4j.setting.enableDebug=false

配置类：

package com.nucarf.config;

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;


@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfiguration {
    
    private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }
    
    @Bean(value = "userApi")
    @Order(value = 1)
    public Docket groupRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(groupApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.nucarf.controller"))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildSettingExtensions());//禁用调试功能
    }

    private ApiInfo groupApiInfo(){
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui很棒~~~！！！")
                .description("<div style='font-size:14px;color:red;'>swagger-bootstrap-ui-demo RESTful APIs</div>")
                .termsOfServiceUrl("http://www.group.com/")
                .contact(new Contact("user","localhost","nucarf@qq.com"))
                .version("1.0")
                .build();
    }

}

实体：

package com.nucarf.entity;

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

@ApiModel(value = "用户")
public class User {

    @ApiModelProperty(value = "id值")
    private Integer id;

    @ApiModelProperty(value = "姓名")
    private String name;

    @ApiModelProperty(value = "年龄")
    private Integer age;

    @ApiModelProperty(value = "工作")
    private String worker;

    @ApiModelProperty(value = "单位")
    private String company;


    public User() {
    }

    public User(Integer id, String name, Integer age, String worker, String company) {
        this.id = id;
        this.name = name;
        this.age = age;
        this.worker = worker;
        this.company = company;
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getWorker() {
        return worker;
    }

    public void setWorker(String worker) {
        this.worker = worker;
    }

    public String getCompany() {
        return company;
    }

    public void setCompany(String company) {
        this.company = company;
    }
}

控制层：

通常我们在开发接口时,比如一个新增接口和一个修改接口,修改接口需要传递主键id、而新增接口则不需要传递此属性,但大部分情况,我们只写一个Model类,此时在新增接口时显示主键id会显得很多余.

使用自定义增强注解ApiOperationSupport中的ignoreParameters属性,可以强制忽略要显示的参数.

忽略的规则如下：

• 例如新增接口时,某实体类不需要显示Id,即可使用该属性对参数进行忽略.ignoreParameters={"id"}
• 如果存在多个层次的参数过滤,则使用名称.属性的方式,例如 ignoreParameters={"uptModel.id","uptModel.uptPo.id"},其中uptModel是实体对象参数名称,id为其属性,uptPo为实体类,作为uptModel类的属性名称
• 如果参数层级只是一级的情况下,并且参数是实体类的情况下,不需要设置参数名称,直接给定属性值名称即可
• 如果实体类属性中是通过List这种数组的方式,那么过滤规则会有所不同,在属性后面需要追加一个下标[0]，ignoreParameters={"uptModel.uptPo[0].id"}

package com.nucarf.controller;


import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.nucarf.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.omg.CORBA.PUBLIC_MEMBER;
import org.springframework.web.bind.annotation.*;

import java.util.Arrays;
import java.util.List;

@Api(tags = "用户模块")
@RestController
public class UserController {

    @ApiOperation(value = "用户列表")
    @PostMapping("userList")
    public List<User> userList(){
        User user1 = new User(1,"张三",20,"初级java开发工程师","阿里巴巴");
        User user2 = new User(2,"李四",21,"中级java开发工程师","百度");
        User user3 = new User(3,"王五",22,"高级java开发工程师","腾讯");
        User user4 = new User(4,"赵六",23,"资深java开发工程师","字节跳动");

        return Arrays.asList(user1,user2,user3,user4);
    }

    @ApiOperation(value = "根据id查询用户")
    @GetMapping("user")
    public User getUser(@RequestParam ("id") @ApiParam(value = "id值",name = "用户id",required = true) Integer id){

        User user = new User(4,"赵六",23,"资深java开发工程师","字节跳动");
        return user;
    }

    @ApiOperation("添加用户信息")
    @ApiOperationSupport(ignoreParameters = {"id"})//新增时，忽略id属性
    @PostMapping("addUser")
    public User addUser(@RequestBody User user){
        return user;
    }

}

启动类：

package com.nucarf;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;

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

效果展示：