文章目录
前言
在日常开发中是需要前后端联调的，接口文档可以实现接口字段等信息共享，swagger提供此功能，knife4j基于swagger进行增强处理。
提示：以下是本篇文章正文内容，下面案例可供参考
一、相关配置
1.网关gateway配置
①.网关增加配置 pom文件
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.2</version>
</dependency>
②.网关增加配置 SwaggerHandler
package com.alpari.gateway.config;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;
import springfox.documentation.swagger.web.*;
import java.util.Optional;
@RestController
public class SwaggerHandler {
@Autowired(required = false)
private SecurityConfiguration securityConfiguration;
@Autowired(required = false)
private UiConfiguration uiConfiguration;
private final SwaggerResourcesProvider swaggerResources;
@Autowired
public SwaggerHandler(SwaggerResourcesProvider swaggerResources) {
this.swaggerResources = swaggerResources;
}
@GetMapping("/swagger-resources/configuration/security")
public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
}
@GetMapping("/swagger-resources/configuration/ui")
public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));
}
@GetMapping("/swagger-resources")
public Mono<ResponseEntity> swaggerResources() {
return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
}
}
③.网关增加配置 SwaggerResourceConfig
package com.alpari.gateway.config;
import org.springframework.cloud.gateway.config.GatewayProperties;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.support.NameUtils;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;
import java.util.ArrayList;
import java.util.List;
@Component
@Primary
public class SwaggerResourceConfig implements SwaggerResourcesProvider {
public static final String API_URI = "v2/api-docs";
private final RouteLocator routeLocator;
private final GatewayProperties gatewayProperties;
public SwaggerResourceConfig(RouteLocator routeLocator, GatewayProperties gatewayProperties) {
this.routeLocator = routeLocator;
this.gatewayProperties = gatewayProperties;
}
@Override
public List<SwaggerResource> get() {
List<SwaggerResource> resources = new ArrayList<>();
List<String> routes = new ArrayList<>();
routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId())).forEach(route -> {
route.getPredicates().stream()
.filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
.forEach(predicateDefinition -> resources.add(swaggerResource(route.getId(),
predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")
.replace("**", API_URI))));
});
return resources;
}
private SwaggerResource swaggerResource(String name, String location) {
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion("2.0");
return swaggerResource;
}
}
④.网关增加配置 SwaggerConfig
package com.alpari.gateway.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(ture) // 是否启用 swagger
.apiInfo(apiInfo()) // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.select() // 设置哪些接口暴露，扫描所有
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 设置标题
.title("标题：xx管理系统_接口文档")
// 描述
.description("描述：...")
// 作者信息
.contact("...")
// 版本
.version("版本号: ...")
.build();
}
}
2.网关过滤器
@Slf4j
@Order(-1) // 保证请求必经此代码
@Component
public class GatewayFilter implements GlobalFilter {
// 匿名可访问的 url，网关过滤器其他代码省略
private static final List<String> ANONYMOUS_URI_LIST = new ArrayList<>();
static {
// 注意：生产环境下面这两个要注释掉，或者用开启停用状态来确保接口文档是否可匿名访问。
ANONYMOUS_URI_LIST.add("/doc.html");
ANONYMOUS_URI_LIST.add("/v2/api-docs");
}
}
二、接口文档使用
前提是：你所开发的接口、实体类上等都配置了相关注解，如 controller 上有 @Api(tags = “用户”)，接口上有 @ApiOperation(“分页列表”)，实体类上有 @ApiModelProperty(value = “用户名称”) 等等相关注解，本篇文档不阐述这方面的知识。
1.访问文档
访问网址：http://ip:port/doc.html，即可看到所有服务的接口文档。
2.查看文档
查看文档：可以看到请求接口、方式、请求类型、参数名称、是否必须等等。
总结
时间并不可真的帮我们去解决哪些问题，它只不过是会把原来怎么也想不通的问题，变得不再重要了。
