Springwolf页面显示异常及/springwolf/docs 404问题求助

1. 为何asyncapi-ui.html可正常显示，但/springwolf/docs返回404？该如何修复？ #

核心原因 #

UI页面仅依赖静态资源即可加载，无需后端接口支撑，但/springwolf/docs是Springwolf生成AsyncAPI文档的核心接口，返回404说明该接口未在Spring容器中注册，或缺少必要的配置、依赖支撑文档生成。常见诱因：

• 未添加Springwolf核心配置注解，文档生成逻辑未启动
• 依赖不全，仅引入UI依赖，未引入核心及RabbitMQ适配依赖
• 使用了过时的配置属性，导致文档接口路径未正确注册
• 代码中无Springwolf可识别的消息生产者/消费者（部分版本中，无扫描目标时文档接口可能无法初始化）

修复步骤 #

• 补全依赖：确保构建文件（Maven/Gradle）中包含Springwolf核心、RabbitMQ适配及UI依赖，版本保持一致：

<!-- Maven示例 -->
<dependencies>
    <dependency>
        <groupId>io.github.springwolf</groupId>
        <artifactId>springwolf-core</artifactId>
        <version>最新稳定版</version>
    </dependency>
    <dependency>
        <groupId>io.github.springwolf</groupId>
        <artifactId>springwolf-rabbitmq</artifactId>
        <version>最新稳定版</version>
    </dependency>
    <dependency>
        <groupId>io.github.springwolf</groupId>
        <artifactId>springwolf-ui</artifactId>
        <version>最新稳定版</version>
    </dependency>
</dependencies>

• 启用核心配置：在Spring Boot启动类或配置类上添加@EnableAsyncApi注解，指定消息组件的扫描包路径：

@SpringBootApplication
@EnableAsyncApi(basePackages = "com.your.service.package")
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}

• 修正配置属性：旧版本的springwolf.paths.docs已废弃，新版本使用springwolf.asyncapi.docs-path配置文档路径，同时开启RabbitMQ支持：

springwolf:
  asyncapi:
    docs-path: /springwolf/docs
    title: 你的服务名称
    version: 1.0.0
  rabbitmq:
    enabled: true

• 确保消息组件可被识别：
  • 消费者需添加@RabbitListener注解
  • 生产者需用@AsyncApiOperation标记消息发送方法，明确消息通道及payload类型：

// 消费者示例
@RabbitListener(queues = "demo-queue")
public void handleDemoMessage(DemoMessage message) {
    // 业务逻辑
}

// 生产者示例
@Service
public class DemoProducer {
    private final RabbitTemplate rabbitTemplate;

    public DemoProducer(RabbitTemplate rabbitTemplate) {
        this.rabbitTemplate = rabbitTemplate;
    }

    @AsyncApiOperation(
            channelName = "demo-queue",
            operationType = AsyncApiOperationType.PUBLISH,
            message = @AsyncApiMessage(payloadType = DemoMessage.class)
    )
    public void sendDemoMessage(DemoMessage message) {
        rabbitTemplate.convertAndSend("demo-queue", message);
    }
}

• 重启服务后，重新访问/springwolf/docs即可获取AsyncAPI JSON文档，UI页面会自动加载完整内容。

2. IntelliJ提示配置属性无法识别是否需要关注？ #

• 该提示仅为IDE层面的元数据缺失告警，不影响服务运行。若需消除提示、获得配置自动补全支持，可添加Springwolf配置元数据依赖：

<!-- Maven示例 -->
<dependency>
    <groupId>io.github.springwolf</groupId>
    <artifactId>springwolf-core</artifactId>
    <version>最新稳定版</version>
    <classifier>metadata</classifier>
    <type>jar</type>
</dependency>

• 若无需IDE自动补全，可直接忽略该提示，只要配置属性符合Springwolf当前版本规范，服务启动后会正常生效。

内容的提问来源于stack exchange，提问作者Pascal