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