springboot+knife4j+nacos實踐

更新時間：2025年06月05日 08:45:40 作者：北漂靚仔

這篇文章主要介紹了springboot+knife4j+nacos實踐,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教

nacos注冊中心聚合OpenAPI文檔

整個工程的目錄

訪問地址：https://github.com/WQL-Java97/doc

工程目錄說明如下

工程	說明
service-user	一個非常簡單的用戶服務(wù)，包含用戶接口
service-order	一個非常簡單的訂單服務(wù)，包含訂單接口
service-doc	聚合文檔工程，也是一個Spring Boot工程，不過需要注意的是基于web的，而非webflux

nacos注冊中心以及service-user、order等都非常簡單，按照注冊中心、用戶服務(wù)、訂單服務(wù)依次進行啟動即可

此時，我們訪問nacos的主頁，最終能看到我們的注冊中心存在兩個服務(wù)，如下圖：

目的：從nacos注冊中心直接進行聚合，也就是將用戶服務(wù)、訂單服務(wù)的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=訂單服務(wù)
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進行查看，效果圖如下 :

注：本項目禁用了調(diào)試功能，具體配置在功能模塊中。

具體實現(xiàn)功能模塊展示：

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
#禁用調(diào)試功能
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());//禁用調(diào)試功能
    }

    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 = "姓名")
    private String name;

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

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

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


    public User() {
    }

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

    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;
    }
}

控制層：

package com.nucarf.controller;


import com.nucarf.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

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("張三",20,"初級java開發(fā)工程師","阿里巴巴");
        User user2 = new User("李四",21,"中級java開發(fā)工程師","百度");
        User user3 = new User("王五",22,"高級java開發(fā)工程師","騰訊");
        User user4 = new User("趙六",23,"資深java開發(fā)工程師","字節(jié)跳動");

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

    @ApiOperation(value = "根據(jù)id查詢用戶")
    @GetMapping("user")
    public User getUser(@RequestParam ("id") @ApiParam(value = "id值",name = "用戶id",required = true) Integer id){

        User user = new User("趙六",23,"資深java開發(fā)工程師","字節(jié)跳動");
        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);
    }
}