Beyond the basic Swagger UI: Adyen 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…
- 10. API standard: What to choose? • Swagger (OpenAPI) • RAML (MuleSoft) • Blueprint (Apiary) • …
- 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
- 15. Format: API first
- 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?
- 22. Adyen: We work in streams
- 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
- 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!