AsyncAPI and Springwolf: Automated documentation and more

AsyncAPI is an open-source initiative that provides a specification to standardize the documentation of event-driven APIs, much like the OpenAPI specification does for REST APIs.
Springwolf, on the other hand, is a practical implementation of the AsyncAPI specification, specifically tailored for Spring Boot applications. It automates the process of documenting event-driven systems, ensuring that the documentation is always synchronized with the actual state of the application.
In this talk, we will focus on learning how Springwolf can help us design and maintain accurate, protocol-agnostic API documentation, automate the generation of AsyncAPI specifications, and provide clear insights into the interactions and functionalities of our event-driven systems, enhancing collaboration and understanding among developers.

Presented @ Spring IO 2024

1. Raphael De Lio
AsyncAPI & Springwolf

2. A little bit of context

3. The three tier application
Presentation Layer
Application Layer
Data Layer

4. The thing is that…
•When we are asked to make a change in
our system, it will likely be a change related
to business
•Since this is an architecture that has high
cohesion of related technology (instead of
high cohesion of business functionality)
•Usually, these changes have to be made in
all layers of our system
Presentation Layer
Application Layer
Data Layer

5. Why do we organize our applications like that?
•A practically universal architecture
•Why is it universal?
Presentation Layer
Application Layer
Data Layer

6. Why do we organize our applications like that?
•Maybe because we are likely to
repeat something that we have seen
before
•Or maybe because of how we
traditionally organize people in
companies
Presentation Layer
Application Layer
Data Layer
Frontend Developers
Java Developers
DB Admins

7. Not a bad architecture. Just optimised over a set of forces that
used to group people based on familiarity

8. These forces have changed
•Aspiration around software development has changed
•We want to ship software much faster than ever before
•We need to make it easier to make changes in our codebase

9. Choosing cohesion of business functionality
•In order to do it, we also need to change how we group code
•This is forcing us to rethink the way our organisations are structured
•Which in turn is forcing us to group people by the way we break our business apart

10. Presentation Layer
Application Layer
Data Layer
•So instead of organizing our codebase like that…

11. Business Line
•We decided to start organizing them like this…
Business Line Business Line Business Line Business Line

12. Product Catalog
Team
•And by organizing our code like this, we can now have dedicated multidisciplinary
teams working on each slice of our application
Order
Management
Team
Payment Team Shipping Team Notification Team

13. •And each of these business lines has its own presentation, business logic and data
layers fully managed by their respective team
Presentation
Application
Model
Presentation
Application
Model
Presentation
Application
Model
Presentation
Application
Model
Presentation
Application
Model

14. •It’s up to the team to decide their architecture and technology used
Product Catalog
Team
Order
Management
Team
Payment Team Shipping Team Notification Team
I need a relational
database
I work better with a
document based database

15. •Now, when we require a change in business to be made, it will likely fall under one dedicated
team with full end to end responsibility of making changes to this specific business
Product Catalog
Team
Order
Management
Team
Payment Team Shipping Team Notification Team
I need a new
notification to
be sent when
an order is
made

16. •There’s still a problem… our communication is still coupled
Product Catalog
Team
Order
Management
Team
Payment Team Shipping Team Notification Team
Notification Team, send a
notification for me!
Okay! Will Do!

17. •It’s also ideal to decouple the communication between our services to a non blocking
communication
Product Catalog
Team
Order
Management
Team
Payment Team Shipping Team Notification Team
An order has been
created!
My cue!

18. •An event is a factual statement about something that has happened
•Other micro-services can listen to the events they are interested in and react accordingly
•The micro-services that listen to the event do not need to be reachable at the time the event
is emitted. And…
•The microservice that is emitting the event doesn’t need to know anything about the
microservices that are listening to the events… Decoupling the communications between
microservices
•The distribution of responsibility we see in our event driven interactions can mirror the
distribution of responsibility we see in our organisations trying to create more autonomous
teams
Event Driven Communication

19. •Our software architecture is usually driven by the way we organize our teams
•We need to release faster than ever before. This forced us to reorganize our teams and
our software architecture
•This force moved us to more decoupled teams, architecture, and communication. We
moved towards micro-services with communications driven by events
Quick Recap

20. •Even though the goal is that we can change our software freely, parts of our service
will still be coupled to other services
•If we break compatibility with the consumers of our events, we will force them to
change as well
•We still need to be able to clearly communicate with other teams the details and
changes of our external contracts
•And that leads us to…
However

21. Async API

22. The need for better communication led us to…
•Started in 2016 at Hitch by Fran Mendez
•Inspired by OpenAPI
•Noticed a wide community was suffering from the
same problems
•Now under the Linux Foundation
•It’s a communication contract between senders
and receivers

23. How does it work?

25. Root elements
Info server
asyncapi
componentsoperationschannel

26. Info
Info
version
title
externalDocs
tags
license
contact
termsOfService
description

27. Servers
server
pathname
host
security
variables
summary
description
protocolVersion
protocol
bindings
externalDocs
tags

28. Channels
channel
title
address
tags
bindings
servers
parameters
messages
description
externalDocs

29. Operations
operations
summary
title
bindings
tags
security
action
channel
description
traits
messages

30. Components
components
servers
schemas
parameters
serverVariables
securitySchemes
messages
operations
channels
correlationIds
repliesreplyAddress
externalDocs
tags
operationTraits
messageTraits
serverBindings
channelBindings
operationBindings
messageBindings

31. Schemas

32. Schemas

33. Messages

34. Reply/Request
operations
summary
title
bindings
tags
security
action
channel
description
traits
messages

35. AsyncAPI Studio

36. Springwolf

37. History
•Created in 2018 by Stav Shamir
•Inspired by SpringFox
•Downloaded more than a half million times
•Compatible with Spring Kafka and Spring Cloud
Stream
•Monthly releases
•Strong and open community
Stav Shamir
Timon Beck Carlos Tasada
Sam0r040

38. What does it do?

39. Automated Documentation Generation
•Automatically creates comprehensive documentation: Analyzes your Spring Boot code to
understand your asynchronous APIs.
•Scans for relevant annotations: Looks for @KafkaListener and @RabbitListener to identify
message interactions.
•Extracts key information: Gathers details about message structure, channels, operations,
and more.

40. AsyncAPI Compliant
•Adherence to AsyncAPI specification: Documentation follows the AsyncAPI standard for
event-driven architectures.
•Standardized structure and format: Familiar to developers experienced with OpenAPI
(Swagger) for REST APIs.
•Improved understanding: Facilitates easier comprehension and adoption of the
asynchronous API by a wider audience.

41. Interactive Web UI
•Web-based interface: Offers a user-friendly way to view and interact with the generated
AsyncAPI documentation.
•Easy navigation: Allows you to explore different parts of the documentation effortlessly.
•Exploration of channels, messages, and operations: Provides detailed insights into the
components of your asynchronous API.
•Enhanced understanding: Facilitates a deeper comprehension of how your asynchronous
API functions.

42. Message Publishing
•Publish messages from the web UI: Send messages to your asynchronous API directly
within the documentation interface.
•Simplified testing and debugging: Allows for convenient interaction with the API during
development and troubleshooting.
•Improved developer experience: Offers a streamlined workflow for testing message
interactions without writing additional code

43. Benefits
•Reduced Manual Effort: You don't have to write and maintain complex AsyncAPI
documentation manually. Springwolf does it for you, saving you time and effort.
•Improved Collaboration: The standardized and interactive documentation makes it easier
for different teams (development, QA, etc.) to collaborate on asynchronous API projects.
•Faster Onboarding: New developers can quickly get up to speed with your asynchronous
API by exploring the generated documentation.
•Enhanced Testing: The message publishing feature (if enabled) simplifies testing and
debugging of your asynchronous API.

44. How does it do it?
•Generates an AsyncAPI file automatically by scanning annotations such as
@KafkaListener, @SqsListener, and @RabbitListener
•Provides a UI allowing us to quickly see which channels our applications interact with
•Generates example payloads for our schemas
•Allows us to send messages to our broker directly from the UI

45. Let’s look at the code

46. What’s next?

47. Try it out!

48. Contribute!

49. Raphael De Lio
•Software Consultant @ Xebia
•Knowledge sharer:
- YouTube
- Medium
- Spring Builders
•Kotlin Dutch User Group Organizer