The Best Practices Behind Best-in-Class API Design | SmartBear Webinar
•
1 like•666 views
In this session, we discussed the best practices of API documentation and highlighted examples of great documentation.
Recommended
Recommended
More Related Content
More from SmartBear
More from SmartBear (20)
Recently uploaded
Recently uploaded (20)
The Best Practices Behind Best-in-Class API Design | SmartBear Webinar
- 1. The Best Practices Behind Best-in-Class API Documentation
- 2. Jonathan Fortunati Manager, Sales Engineering SmartBear Your Hosts for Today Proprietary & Confidential 2 Patrick Londa Marketing Manager SmartBear
- 3. 2009 6.5M+ users 11 22,000+ 5 525+ customers employees founded global offices free tools
- 5. Utilizing the OpenAPI specification Best practices for API documentation The current API documentation landscape How SwaggerHub facilitates these best practices Questions & Answers • • • • • 5 Agenda
- 7. The 2019 State of API Report 7
- 8. The 2019 State of API Report 8
- 9. The 2019 State of API Report 9
- 10. The 2019 State of API Report 10
- 11. The 2019 State of API Report 11
- 12. The 2019 State of API Report 12
- 13. Best Practices for API Documentation
- 14. • Tell a story What Makes Good Documentation? https://developer.marvel.com/docs 14
- 15. • Tell a story • Make it interactive What Makes Good Documentation? 15 https://developer.marvel.com/docs
- 16. • Tell a story • Make it interactive • Examples + exercises What Makes Good Documentation? 16 https://developer.marvel.com/docs
- 17. • Tell a story • Make it interactive • Examples + exercises • Link everything What Makes Good Documentation? 17 https://developer.marvel.com/docs
- 18. • Tell a story • Make it interactive • Examples + exercises • Link everything • FAQs What Makes Good Documentation? 18 https://developer.marvel.com/docs
- 19. • Tell a story • Make it interactive • Examples + exercises • Link everything • FAQs • Keep it up to date What Makes Good Documentation? 19 https://developer.marvel.com/docs
- 20. • Tell a story • Make it interactive • Examples + exercises • Link everything • FAQs • Keep it up to date What Makes Good Documentation? 20 • Provide a clear starting point
- 21. • Tell a story • Make it interactive • Examples + exercises • Link everything • FAQs • Keep it up to date What Makes Good Documentation? 21 • Provide a clear starting point • Maintain a clear structure
- 22. • Tell a story • Make it interactive • Examples + exercises • Link everything • FAQs • Keep it up to date What Makes Good Documentation? 22 • Provide a clear starting point • Maintain a clear structure • Encourage feedback from users
- 23. • Tell a story • Make it interactive • Examples + exercises • Link everything • FAQs • Keep it up to date What Makes Good Documentation? 23 • Provide a clear starting point • Maintain a clear structure • Encourage feedback from users • Write for humans first
- 24. • Tell a Story • Make it interactive • Examples + exercises • Link everything • FAQs • Keep it up to date What Makes Good Documentation? 24 • Provide a clear starting point • Maintain a clear structure
- 28. The 2019 State of API Report 28
- 29. The 2019 State of API Report 29
- 30. The 2019 State of API Report 30
- 31. The 2019 State of API Report 31
- 32. Contract for defining RESTful APIs • Ask user focused questions before coding • ‘What information do our users want?’ • ‘How can they access it?’ Open source, evolving standard • How is it different from Swagger? Ecosystem of tools + support Acts as a source of truth for: • Development • Testing • Documentation What is the OAS? 32
- 33. Swagger UI • First solution built on top of the specification • Interactive documentation • Easily parse OAS and render in browser • Customizable + extendable Swagger Editor • Quickly create and update OAS Swagger Core • Annotate existing code • Tie code directly to documentation • Verify build-specs against design-specs SwaggerHub • Platform solution tying together distributed tools • User + project management • Built in integrations Tools for OpenAPI 33
- 34. Best-in-Class API Documentation with SwaggerHub
- 35. The Collaboration Platform for OAS API Design and Documentation Improve Collaboration Enforce Intelligent Standards Seamless Integration Create workspaces, get feedback, and provide more flexible access to the users who need it in a single platform designed to support using the OpenAPI Specification (OAS) at scale Define reusable assets in a central library or build out robust style guidelines for new APIs to cut down on issues and bugs later in the development process Don’t change the way you work to support new tools – we hook into a wide range of API platforms and services, as well as offering a robust back end for more customized integrations {API-1} {API-2}
- 36. Thank you! Q&A