AsyncAPI and Srpingwolf

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

Transcript

1. Raphael De Lio AsyncAPI & Springwolf
2. A little bit of context
3. The three tier application Present a tion L a yer Applic a tion L a yer D a t a L a yer
4. The thing is that… • When we a re a sked to m a ke a ch a nge in our system, it will likely be a ch a nge rel a ted to business • Since this is a n a rchitecture th a t h a s high cohesion of rel a ted technology (inste a d of high cohesion of business function a lity) • Usu a lly, these ch a nges h a ve to be m a de in a ll l a yers of our system Present a tion L a yer Applic a tion L a yer D a t a L a yer
5. Why do we organize our applications like that? • A pr a ctic a lly univers a l a rchitecture • Why is it univers a l? Present a tion L a yer Applic a tion L a yer D a t a L a yer
6. Why do we organize our applications like that? • M a ybe bec a use we a re likely to repe a t something th a t we h a ve seen before • Or m a ybe bec a use of how we tr a dition a lly org a nize people in comp a nies Present a tion L a yer Applic a tion L a yer D a t a L a yer Frontend Developers J a v a Developers DB Admins
7. Not a b a d a rchitecture. Just optimised over a set of forces th a t used to group people b a sed on f a mili a rity
8. These forces have changed • Aspir a tion a round softw a re development h a s ch a nged • We w a nt to ship softw a re much f a ster th a n ever before • We need to m a ke it e a sier to m a ke ch a nges in our codeb a se
9. Choosing cohesion of business functionality • In order to do it, we a lso need to ch a nge how we group code • This is forcing us to rethink the w a y our org a nis a tions a re structured • Which in turn is forcing us to group people by the w a y we bre a k our business a p a rt
10. Present a tion L a yer Applic a tion L a yer D a t a L a yer • So inste a d of org a nizing our codeb a se like th a t…
11. Business Line • We decided to st a rt org a nizing them like this… Business Line Business Line Business Line Business Line
12. Product C a t a log Te a m • And by org a nizing our code like this, we c a n now h a ve dedic a ted multidisciplin a ry te a ms working on e a ch slice of our a pplic a tion 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
13. • And e a ch of these business lines h a s its own present a tion, business logic a nd d a t a l a yers fully m a n a ged by their respective te a m Present a tion Applic a tion Model Present a tion Applic a tion Model Present a tion Applic a tion Model Present a tion Applic a tion Model Present a tion Applic a tion Model
14. • It’s up to the te a m to decide their a rchitecture a nd technology used 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 I need a rel a tion a l d a t a b a se I work better with a document b a sed d a t a b a se
15. • Now, when we require a ch a nge in business to be m a de, it will likely f a ll under one dedic a ted te a m with full end to end responsibility of m a king ch a nges to this speci f ic business 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 I need a new noti f ic a tion to be sent when a n order is m a de
16. • 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!
17. • 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!
18. • An event is a f a ctu a l st a tement a bout something th a t h a s h a ppened • Other micro-services c a n listen to the events they a re interested in a nd re a ct a ccordingly • The micro-services th a t listen to the event do not need to be re a ch a ble a t the time the event is emitted. And… • The microservice th a t is emitting the event doesn’t need to know a nything a bout the microservices th a t a re listening to the events… Decoupling the communic a tions between microservices • The distribution of responsibility we see in our event driven inter a ctions c a n mirror the distribution of responsibility we see in our org a nis a tions trying to cre a te more a utonomous te a ms Event Driven Communication
19. • Our softw a re a rchitecture is usu a lly driven by the w a y we org a nize our te a ms • 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 a nd our softw a re a rchitecture • This force moved us to more decoupled te a ms, a rchitecture, a nd communic a tion. We moved tow a rds micro-services with communic a tions driven by events Quick Recap
20. • Even though the go a l is th a t we c a n ch a nge our softw a re freely, p a rts of our service will still be coupled to other services • If we bre a k comp a tibility with the consumers of our events, we will force them to ch a nge a s well • We still need to be a ble to cle a rly communic a te with other te a ms the det a ils a nd ch a nges of our extern a l contr a cts • And th a t le a ds us to… However
21. Async API
22. 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
23. How does it work?
25. Root elements Info server a sync a pi components oper a tions ch a nnel
26. Info Info version title extern a lDocs t a gs license cont a ct termsOfService description
27. 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
28. Channels ch a nnel title a ddress t a gs bindings servers p a r a meters mess a ges description extern a lDocs
29. 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
30. 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
31. Schemas
32. Schemas
33. Messages
34. 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
35. AsyncAPI Studio
36. Springwolf
37. 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
38. What does it do?
39. Automated Documentation Generation • Autom a tic a lly cre a tes comprehensive document a tion: An a lyzes your Spring Boot code to underst a nd your a synchronous APIs. • 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.
40. AsyncAPI Compliant • Adherence to AsyncAPI speci f ic a tion: Document a tion follows the AsyncAPI st a nd a rd for event-driven a rchitectures. • St a nd a rdized structure a nd form a t: F a mili a r to developers experienced with OpenAPI (Sw a gger) for REST APIs. • Improved underst a nding: F a cilit a tes e a sier comprehension a nd a doption of the a synchronous API by a wider a udience.
41. Interactive Web UI • Web-b a sed interf a ce: 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. • E a sy n a vig a tion: Allows you to explore di ff erent p a rts of the document a tion e ff ortlessly. • Explor a tion of ch a nnels, mess a ges, a nd oper a tions: Provides det a iled insights into the components of your a synchronous API. • Enh a nced underst a nding: F a cilit a tes a deeper comprehension of how your a synchronous API functions.
42. Message Publishing • Publish mess a ges from the web UI: Send mess a ges to your a synchronous API directly within the document a tion interf a ce. • Simpli f ied testing a nd debugging: Allows for convenient inter a ction with the API during development a nd troubleshooting. • Improved developer experience: O ff ers a stre a mlined work f low for testing mess a ge inter a ctions without writing a ddition a l code
43. Bene f its • Reduced M a nu a l E ff ort: You don't h a ve to write a nd m a int a in complex AsyncAPI document a tion m a nu a lly. Springwolf does it for you, s a ving you time a nd e ff ort. • Improved Coll a bor a tion: The st a nd a rdized a nd inter a ctive document a tion m a kes it e a sier for di ff erent te a ms (development, QA, etc.) to coll a bor a te on a synchronous API projects. • F a ster Onbo a rding: New developers c a n quickly get up to speed with your a synchronous API by exploring the gener a ted document a tion. • Enh a nced Testing: The mess a ge publishing fe a ture (if en a bled) simpli f ies testing a nd debugging of your a synchronous API.
44. How does it do it? • Gener a tes a n AsyncAPI f ile a utom a tic a lly by sc a nning a nnot a tions such a s @K af k a Listener, @SqsListener, a nd @R a bbitListener • Provides a UI a llowing us to quickly see which ch a nnels our a pplic a tions inter a ct with • Gener a tes ex a mple p a ylo a ds for our schem a s • Allows us to send mess a ges 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 • Softw a re Consult a nt @ Xebi a • Knowledge sh a rer: - YouTube - Medium - Spring Builders • Kotlin Dutch User Group Org a nizer