Raphael De Lio AsyncAPI & Springwolf Automatic Documentation and more…  1

Application Layer Presentation Layer Database Layer 2

“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

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

5

6 Team A Team B

Conway’s law is about the limitations of the human ability to communicate. 7

If we go back time… IT Director System Analysts Project Managers Frontend Backend Operations DBA 8

Application Layer Presentation Layer Database Layer 9 A system designed by this organization, would be similar to:

Which is totally fi ne! 10

The whole IT department was seen as a support unit, not a strategic one. 11

12

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 • 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!

• 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!

Event Driven Communication 16

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 Team A Team B

AsyncAPI 19

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

How does it work?

No content

Root elements Info server a sync a pi components oper a tions ch a nnel

Info Info version title extern a lDocs t a gs license cont a ct termsOfService description

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

Channels ch a nnel title a ddress t a gs bindings servers p a r a meters mess a ges description extern a lDocs

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

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

Schemas

Schemas

Messages

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

AsyncAPI Studio

Springwolf

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

What does it do?

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.

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.

Let’s look at the code

What’s next?

Try it out!

Contribute!

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