使用 SpringWolf 自动生成异步 API 文档

930

异步通信在现代分布式系统中变得越来越重要，它允许不同组件在无需时间同步的情况下高效交互。这在强调独立性和扩展性的微服务架构中尤为重要。实现异步通信的常用技术和协议包括Apache Kafka、RabbitMQ和AMQP协议。

虽然异步消息系统提升了扩展性和弹性，但也带来了维护清晰且最新文档的挑战。正如REST API受益于**OpenAPI（原Swagger）**的自动文档生成，事件驱动架构也需要类似的解决方案。

为什么文档如此重要？

• 帮助开发者理解微服务生态中的事件流
• 简化新成员的入职流程
• 降低跨团队沟通成本
• 促进与外部系统的集成

SpringWolf：异步通信的OpenAPI

如同Springdoc OpenAPI为REST服务自动生成文档，SpringWolf为异步消息系统提供同样功能。它通过扫描Kafka生产者和消费者生成AsyncAPI规范，并提供交互式UI来探索和测试事件驱动API。

通过SpringWolf，您可以：

• 自动文档化Kafka主题和消息格式
• 提供类似Swagger/OpenAPI的UI（专为事件驱动架构设计）
• 减少手动维护文档的工作量

实战：使用Spring Boot实现Kafka生产者与消费者

本章节将使用Spring Boot创建Java应用，演示Kafka消费者的实现。

1. 运行本地Kafka

首先需要启动本地Kafka供应用监听事件。

使用以下docker-compose文件：

version: "3"

services:
  zookeeper:
    image: confluentinc/cp-zookeeper:5.4.0
    hostname: zookeeper
    container_name: zookeeper
    ports:
      - "2181:2181"
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

  broker:
    image: confluentinc/cp-server:5.4.0
    hostname: broker
    container_name: broker
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: "zookeeper:2181"
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://broker:29092,PLAINTEXT_HOST://localhost:9092
      KAFKA_METRIC_REPORTERS: io.confluent.metrics.reporter.ConfluentMetricsReporter
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_CONFLUENT_LICENSE_TOPIC_REPLICATION_FACTOR: 1
      CONFLUENT_METRICS_REPORTER_BOOTSTRAP_SERVERS: broker:29092
      CONFLUENT_METRICS_REPORTER_ZOOKEEPER_CONNECT: zookeeper:2181
      CONFLUENT_METRICS_REPORTER_TOPIC_REPLICAS: 1
      CONFLUENT_METRICS_ENABLE: "true"
      CONFLUENT_SUPPORT_CUSTOMER_ID: "anonymous"

2. 创建Spring Boot消费者应用

通过Spring Initializr或IDE创建新的Spring Boot项目。

在_pom.xml_中添加依赖：

<dependencies>
    <!-- Spring Kafka依赖 -->
    <dependency>
        <groupId>org.springframework.kafka</groupId>
        <artifactId>spring-kafka</artifactId>
    </dependency>

    <!-- SpringWolf Kafka依赖 -->
    <dependency>
        <groupId>io.github.springwolf</groupId>
        <artifactId>springwolf-kafka</artifactId>
        <version>1.10.0</version>
    </dependency>

    <!-- SpringWolf UI依赖 -->
    <dependency>
        <groupId>io.github.springwolf</groupId>
        <artifactId>springwolf-ui</artifactId>
        <version>1.10.0</version>
    </dependency>
</dependencies>

Gradle用户请使用：

implementation 'org.springframework.kafka:spring-kafka'
implementation 'io.github.springwolf:springwolf-kafka:1.9.0'
runtimeOnly 'io.github.springwolf:springwolf-ui:1.9.0'

3. Kafka + SpringWolf配置

在_application.properties_或_application.yml_中添加配置：

spring.application.name=spring-wolf-kafka-app

# Kafka配置
spring.kafka.bootstrap-servers=localhost:9092
spring.kafka.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer
spring.kafka.producer.value-serializer=org.apache.kafka.common.serialization.StringSerializer
spring.kafka.template.default-topic=wolf-topic

# Springwolf配置
springwolf.enabled=true
springwolf.docket.base-package=br.com.ldf.medium.app.infrastructure
springwolf.docket.info.title=${spring.application.name}
springwolf.docket.info.version=1.0.0
springwolf.docket.info.description=Baeldung教程应用，演示如何使用Springwolf生成AsyncAPI文档
springwolf.docket.servers.kafka-server.protocol=kafka
springwolf.docket.servers.kafka-server.host=http://localhost:9092

4. 实现Kafka消费者

• 创建_Listener_类监听Kafka主题消息
• 创建_UserPayloadDTO_作为契约

@Slf4j
@Component
public class Listener {

    @KafkaListener(topics = "wolf-topic", groupId = "wolf-group")
    public void consume(UserPayloadDTO userPayloadDTO) {
        log.info("Consuming message: {}", userPayloadDTO);
    }
}

public record UserPayloadDTO(
        String name,
        String email
) {
}

SpringWolf与AsyncAPI集成

通过SpringWolf，AsyncAPI文档会自动生成。应用启动后，可通过以下地址访问SpringWolf-UI：

http://localhost:8080/springwolf/asyncapi-ui.html

SpringWolf核心功能

通道与操作：

• 通道代表Kafka主题（如wolf-topic）
• 操作定义服务是发布还是消费消息
• wolf-topic标记为RECEIVE，表示应用是该主题的消费者

消息绑定：

• 定义Kafka特定配置，包括：
Kafka绑定版本（”0.5.0″）
消费者组ID（如”wolf-group”）
内容类型（application/json）

负载模式文档：

• _UserPayloadDTO_自动生成JSON结构文档：

{
  "email": "string",
  "name": "string"
}

• 帮助开发者理解消息格式

头部信息：

• 列出消息中使用的Kafka头部，如__TypeId__（标识反序列化Java类）
• 对调试序列化/反序列化问题非常有用

多服务器支持：

• Servers列表中显示Kafka-Server，支持多消息代理文档化

交互式UI：

• 开发者可探索所有主题、绑定和消息格式
• “复制”按钮方便复制示例负载
• “发布”按钮（默认禁用）支持直接从UI发送消息

对开发者的价值

• ✅ 提升事件驱动系统的可见性
• ✅ 减少手动维护Kafka主题文档的工作量
• ✅ 加速新成员上手
• ✅ 确保API契约清晰定义

项目参考：https://github.com/ice-lfernandes/spring-wolf-kafka-app

参考资料

• https://www.springwolf.dev/
• https://github.com/springwolf/springwolf-core

结论

本文通过Kafka消费者示例，展示了如何轻松文档化事件驱动架构。借助SpringWolf，我们拥有了类似OpenAPI的工具，能够以极其简便的方式为消费应用事件提供友好的用户界面。

感谢您的耐阅读，请持续关注新文章和更新！

评分

欢迎为Ta评分