Adyen provides an API explorer that enhances the traditional Swagger UI, supporting over 250 payment methods across various countries. The document outlines developer challenges with existing API documentation and highlights improvements such as better code samples, adaptive layout, and a clean structure for nested objects. It encourages collaboration between tech writers and developers, promotes the use of the latest OpenAPI standards, and invites feedback on the API explorer.

1. Adyen API Explorer
Beyond the basic Swagger UI
wherever people payAleksei Akimov

2. Adyen accepts payments
over any sales channel

3. Adyen: 250+ payment methods
China
Netherlands
France
UKBelgium
World
Canada
US
Mexico
Portugal
Europe
Russia
Sweden
South Korea
Austria
Poland
Malaysia
Japan
Philippines
Indonesia
Australia
Thailand
Denmark
Germany
Finland
Brasil

5. 2008 2010 2012 2014 2016
Annual processing: over $100B
2017

6. Docs: Main
challenges
• Release cycle: 3-4 weeks
• 10+ APIs, different versions
• Impact of a single mistake is huge
• Scaling x100 means merchants must be
able to integrate with the docs only

7. User persona:
developer
Frustrations: Outdated code samples,
difficulty finding what he’s looking for.
What makes Dave happy: As a developer,
Dave is used to working with and relying on
docs.
Good API documentation = happy Dave.
Questions: “Where can I find typical
responses from APIs?”
Hi, I'm Dave
Should we integrate with Adyen?

8. Tech docs:
Automatic
generation
• Technical accuracy
• Consistency
• Up-to-date information
• Testing
• Flexible templating
• much more…

9. From API
to documentation

10. API standard: What to choose?
• Swagger (OpenAPI)
• RAML (MuleSoft)
• Blueprint (Apiary)
• …

11. Swagger: Linux foundation

12. Swagger: Pros
• Supported by Linux foundation
• Exists from 2010
• Steadily evolves
• RAML (Mulesoft) and Blueprint
(Apiary) recently joined OAS

13. Swagger vs OpenAPI
OpenAPI
Specification
Swagger
Tools for implementing
the specification

14. Format: OpenAPI Specification

15. Format: API first

16. From specification
to documentation

17. Swagger UI: Only for simple APIs

18. Swagger UI: Ineffective layout

19. Swagger UI: Problems with nested structures

20. How can we
go beyond?

21. Dave
Learning
Dave
Coding

22. Adyen: We work in streams

24. Demo:
https://docs.adyen.com/api-explorer/

25. API Explorer: First wins
1. Support for multiple specs - more products and
versions
2. Groups and sorting for endpoints
3. Adaptive layout
4. Clean structure for nested objects
5. Multiple code examples
6. Rich JSON editor
7. Branded design

26. Tips & Tricks

27. Let techwriters and
developers
collaborate on the
same content
This is a bench.

28. Always use the
latest version of
OpenAPI
• Callbacks
• Relationships between
operations
• Cookie parameters
• …

29. Use markdown

30. Integrate Swagger
in CI

31. OpenAPI supports
custom
annotations ;-)

32. Launch fast and iterate

33. We need YOU!
• Visit https://docs.adyen.com/api-explorer/
and let us know what you think
• If you are working on a similar project,
contacts us
• We are hiring!

34. Thank you!
Questions?
wherever people pay