Two years ago, Adyen realized the Swagger UI wasn’t meeting their needs... so they decided to build their own. We’ll share how we designed and built our new API Explorer - making it more extendable, and easier for Developers and Technical Writers to maintain. We’ll also talk about our future plans, including open sourcing it for the community.

1. Open sourcing
Adyen’s API
explorer.

2. Karl Salisbury
Senior Product Designer at Adyen
Work on Adyen documentation

3. About me.
● Designing since 2002.
● Worked on lots of different
types of projects.
● 🇳🇱 Live in the Netherlands
not Dutch (from 🐨 Australia).
● Not a developer, but I have
dabbled in code and talk to
developers a lot.
● Solve problems with design.

4. The docs team.
● 8x technical writers
● 3x developers
● 1x product manager
● We 💚 making docs
● Make documentation great

5. The
people
involved.
A - Z
Arjen
Designer
Ruby
Tech
writer
Andrea
Tech
writer
Johan
Developer
Paula
Tech
writer
Miguel
Tech lead
Sam
Product
manager
Wilson
Developer
Ruslan
Tech
writer

6. What I’ll
be talking
about today.
1. What is Adyen
2. History of
API Explorer
3. Open sourcing
4. Live demo
5. Questions

7. 1.What is Adyen?

8. The payments
platform built
for growth.

9. How Adyen’s
product works.

10. Pay online Pay by link Pay in store

11. What makes
Adyen unique?

12. We work
with lots
of different
merchants.

13. Different business
models
Different
currencies
Local payment
methods

14. So our APIs
need to be
flexible.

15. A simple
payment
request.

16. A complex
payment
request.

17. 2. API Explorer

18. And we improved our API
explorer over time.

19. Let’s go
back in time.

20. In the beginning...
We were using
PDFs to document
our APIs

21. Then we
got Swagger.

22. But there were
some problems.
● Swagger files don’t provide
much context
● Too many swagger files
● 2 references to maintain and
for the merchant to use
● A single endpoint could have
20 use cases

23. So we built
the very first
API explorer.

24. Some problems:
Hard to maintain.
Usability problems.
Old tech stack.

25. So eventually we
outgrew our old
API explorer.

26. So we
made API
explorer 2.0

27. 3. Why will we open source it?

28. It’s a great
way to give
back to the
community.

29. You have to
think about
different use
cases and
audiences.

30. You have to
think about
flexibility and
extensibility.

31. Make your
code more
maintainable.

32. So open source
challenges you
to do things
better.

33. Improvements we made

34. Compatible
with the
Open API
standard. 3.1

35. We improved
the usability.

38. It has support
for dark mode.

40. We also made it
mobile friendly.

42. 4. Now for a live
demonstration.

43. Takeaways
1. Product development is iterative.
2. Open source gives back to the
community and leads to better
software.
3. Consider creating open source
projects or contributing to others.

44. 5. Questions?

45. Call for beta testers
developer-experience@adyen.com

46. We’re hiring
Tech Writers & Developers
Careers.Adyen.com

47. Thank you!