springboot+knife4j+nacos实践
目录
- nacos注册中心聚合OpenAPI文档
- 整个工程的目录
- 工程目录说明如下
- 主要步骤如下
- 总结
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> <javascriptdependencies> <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:schemaLocatiopythonn="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 #禁用调php试功能 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 @EnableSwagger2WpythonebMvc 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 = "姓名") 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 compphpany) { 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开发工程师","阿里巴巴"); User user2 = new User("李四",21,"中级java开发工程师","百度"); User user3 = new User("王五",22,"高级java开发工程师","腾讯"); User user4 = new User("赵六",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("赵六",23,"资深java开发工程师","字节跳动"); 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); } }
- 效果展示:
总结
以上为个人经验,希望能给大家一个参考,也希望大家多多支持编程客栈(www.devze.com)。
精彩评论