AsyncAPI and Springwolf v2

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 @ Devoxx Belgium 2024

Transcript

1. Raphael De Lio AsyncAPI & Springwolf Automatic Documentation and more…  1
2. Application Layer Presentation Layer Database Layer 2
3. “Any organization that designs a system will produce a design whose structure is a copy of the organization's internal communication structure.” - Melvin Conway 3
4. The cognitive load one person needs to solve a problem alone is in fi nitely lower than the cognitive load a group of people need to solve a problem together. 4
6. 6 Team A Team B
7. Conway’s law is about the limitations of the human ability to communicate. 7
8. If we go back time… IT Director System Analysts Project Managers Frontend Backend Operations DBA 8
9. Application Layer Presentation Layer Database Layer 9 A system designed by this organization, would be similar to:
10. Which is totally fi ne! 10
11. The whole IT department was seen as a support unit, not a strategic one. 11
13. 13 Product C a t a log Te a m Order M a n a gement Te a m P a yment Te a m Shipping Te a m Noti f ic a tion Te a m
14. 14 • There’s still a problem… our communic a tion is still coupled Product C a t a log Te a m Order M a n a gement Te a m P a yment Te a m Shipping Te a m Noti f ic a tion Te a m Noti f ic a tion Te a m, send a noti f ic a tion for me! Ok a y! Will Do!
15. • It’s a lso ide a l to decouple the communic a tion between our services to a non blocking communic a tion Product C a t a log Te a m Order M a n a gement Te a m P a yment Te a m Shipping Te a m Noti f ic a tion Te a m An order h a s been cre a ted! My cue!
16. Event Driven Communication 16
17. Quick recap • We need to rele a se f a ster th a n ever before. • This forced us to reorg a nize our te a ms so th a t we could reorg a nize the design of our systems • Communic a tion a mong hum a ns is still limited to the cognitive lo a d hum a ns c a n lo a d • Communic a tion a cross te a ms will a lw a ys exist 17
18. 18 Team A Team B
19. AsyncAPI 19
20. The need for better communication led us to… • St a rted in 2016 a t Hitch by Fr a n Mendez • Inspired by OpenAPI • Noticed a wide community w a s su ff ering from the s a me problems • Now under the Linux Found a tion • It’s a communic a tion contr a ct between senders a nd receivers
21. How does it work?
23. Root elements Info server a sync a pi components oper a tions ch a nnel
24. Info Info version title extern a lDocs t a gs license cont a ct termsOfService description
25. Servers server p a thn a me host security v a ri a bles summ a ry description protocolVersion protocol bindings extern a lDocs t a gs
26. Channels ch a nnel title a ddress t a gs bindings servers p a r a meters mess a ges description extern a lDocs
27. Operations oper a tions summ a ry title bindings t a gs security a ction ch a nnel description tr a its mess a ges
28. Components components servers schem a s p a r a meters serverV a ri a bles securitySchemes mess a ges oper a tions ch a nnels correl a tionIds replies replyAddress extern a lDocs t a gs oper a tionTr a its mess a geTr a its serverBindings ch a nnelBindings oper a tionBindings mess a geBindings
29. Schemas
30. Schemas
31. Messages
32. Reply/Request oper a tions summ a ry title bindings t a gs security a ction ch a nnel description tr a its mess a ges
33. AsyncAPI Studio
34. Springwolf
35. History • Cre a ted in 2018 by St a v Sh a mir • Inspired by SpringFox • Downlo a ded more th a n a h a lf million times • Comp a tible with Spring K a f k a a nd Spring Cloud Stre a m • Monthly rele a ses • Strong a nd open community St a v Sh a mir Timon Beck C a rlos T a s a d a S a m0r040
36. What does it do?
37. Automated Documentation Generation • Sc a ns for relev a nt a nnot a tions: Looks for @K af k a Listener a nd @R a bbitListener to identify mess a ge inter a ctions. • Extr a cts key inform a tion: G a thers det a ils a bout mess a ge structure, ch a nnels, oper a tions, a nd more. AsyncAPI Compliant • Follows the AsyncAPI st a nd a rd for event-driven a rchitectures. • F a mili a r to developers experienced with OpenAPI (Sw a gger) for REST APIs.
38. Interactive Web UI • O ff ers a user-friendly w a y to view a nd inter a ct with the gener a ted AsyncAPI document a tion. • F a cilit a tes a deeper comprehension of how your a synchronous API functions. Message Publishing • Send mess a ges to your a synchronous API directly within the document a tion interf a ce. • Allows for convenient inter a ction with the API during development a nd troubleshooting.
39. Let’s look at the code
40. What’s next?
41. Try it out!
42. Contribute!
43. Raphael De Lio • Softw a re Consult a nt @ Xebi a • AsyncAPI Amb a ss a dor • Dutch Kotlin MeetUp Org a nizer • Knowledge sh a rer: - YouTube - Medium