springcloud gateway结合knife4j生成Api文档

最新推荐文章于 2024-11-13 15:47:48 发布

原创最新推荐文章于 2024-11-13 15:47:48 发布 · 758 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#java

springcloud gateway 专栏收录该内容

5 篇文章

订阅专栏

本文档介绍了如何在SpringCloudGateway项目中，通过引入Knife4j的相关依赖，实现接口模块与网关模块的配置，以生成详细的API文档。主要步骤包括：1) 在接口模块引入knife4j-micro-spring-boot-starter依赖并配置Swagger；2) 在网关模块引入knife4j-spring-boot-starter依赖，并提供获取swagger资源的接口；3) 自定义Swagger资源配置，确保所有服务的API文档能够被正确聚合展示。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

springcloud gateway结合knife4j生成Api文档

学习中笔记

一、接口模块（mxm-system-api）引入依赖

		<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-micro-spring-boot-starter</artifactId>
        </dependency>

进行swagger个性化配置

@Configuration
@EnableSwagger2
public class SwagggerConfig extends BaseSwaggerConfig {

    @Override
    public SwaggerProperties swaggerProperties() {
        return SwaggerProperties.builder()
                .apiBasePackage("com.mxm.systemapi.controller")
                .title("XXX项目接口文档")
                .description("XXX项目接口文档")
                .contactName("tsui")
                .version("1.0")
                .build();
    }
}

继承的BaseSwaggerConfig做了Swagger的基础配置

public abstract class BaseSwaggerConfig {
	@Bean
    public Docket createRestApi() {
        SwaggerProperties swaggerProperties = swaggerProperties();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo(swaggerProperties))
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApiBasePackage()))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    private ApiInfo apiInfo(SwaggerProperties swaggerProperties) {
        return new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail()))
                .version(swaggerProperties.getVersion())
                .build();
    }

    public abstract SwaggerProperties swaggerProperties();
}

二、网关模块（mxm-gateway）引入依赖

		<dependency>
	        <groupId>com.github.xiaoymin</groupId>
	        <artifactId>knife4j-spring-boot-starter</artifactId>
	    </dependency>

获取swagger信息接口

@RestController
@RequestMapping("/swagger-resources")
public class SwaggerController {

    @Autowired(required = false)
    private SecurityConfiguration securityConfiguration;

    @Autowired(required = false)
    private UiConfiguration uiConfiguration;

    private final SwaggerResourcesProvider swaggerResources;

    @Autowired
    public SwaggerHandler(SwaggerResourcesProvider swaggerResources) {
        this.swaggerResources = swaggerResources;
    }

    /**
     * Swagger安全配置，支持oauth和apiKey设置
     */
    @GetMapping("/configuration/security")
    public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
    }

    /**
     * Swagger UI配置
     */
    @GetMapping("/configuration/ui")
    public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));
    }

    /**
     * Swagger资源配置，微服务中这各个服务的api-docs信息
     */
    @GetMapping("")
    public Mono<ResponseEntity> swaggerResources() {
        return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
    }
}

Swagger资源配置

@Slf4j
@Component
@Primary
@AllArgsConstructor
public class SwaggerResourceConfig implements SwaggerResourcesProvider {

    private final RouteLocator routeLocator;
    private final GatewayProperties gatewayProperties;

    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<String> routes = new ArrayList<>();
        //获取所有路由的ID
        routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
        //过滤出配置文件中定义的路由->过滤出Path Route Predicate->根据路径拼接成api-docs路径->生成SwaggerResource
        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("**", "v2/api-docs"))));
        });

        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location) {
        log.info("name:{},location:{}", name, location);
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion("2.0");
        return swaggerResource;
    }
}