OpenAPI Secrets for Generating Code & Docs Which Work!
Your API is language agnostic, but your API consumers are not. When Developers Integrate with an API, they do so in their favourite programming language. With the help of an API specification, you can automatically generate up to 90% of the integration code (as SDKs and Code Samples) and save them heaps of time. The problem is, OpenAPI and other API specification formats are not built with code generation requirements in mind, thus we often see Code Generators creating unusable code for syntactically correct API specifications. This talk will demonstrate how you can carefully craft an API specification to generate production-quality SDKs and API portals. It will help you understand how trivial issues like inline anonymous schemas and naming conventions can have a big impact on the generated output. And how the right kind of validation and linting process can help you overcome all of these issues efficiently in order to help you build a world-class Developer Experience.
Empfohlen
Empfohlen
Weitere ähnliche Inhalte
Ähnlich wie OpenAPI Secrets for Generating Code & Docs Which Work!
Ähnlich wie OpenAPI Secrets for Generating Code & Docs Which Work! (20)
Kürzlich hochgeladen
Kürzlich hochgeladen (20)
OpenAPI Secrets for Generating Code & Docs Which Work!
- 1. OpenAPI Secrets For Generating Code & Docs Which Work!
- 2. Which Machine Readable API Definition Format Do You Use? 2 OpenAPI? RAML? Postman? Insomnia? API Blueprint, WADL, WSDL, IODocs, HAR, Google Discovery?
- 3. 3 0" 700" 1400" 2100" 2800" 3500" A P I M A T I C ' I O D o c s ' R A M L ' W A D L ' S w a g g e r Y a m l ' G o o g l e D i s c o v e r y ' M a s h a p e ' S w a g g e r ' A P I B l u e P r i n t ' 71' 104' 390' 525' 550' 3039' 962' 3041' 2834' 68' 104' 200' ''''''''295' '''''''322' '''476' 962' 1948' 2614' All'IDFs' Unique'IDFs' Analysis of 11516 API Definitions From APIDays, 2016
- 4. 4
- 5. 01,041,706 APIs Transformed and counting … 5
- 7. 7
- 8. 8
- 9. 9
- 10. WHY Do we are about this data? 10
- 11. 11 APIMatic
- 12. 12
- 13. Common Mistakes Developers Make In Their OpenAPI 3 Files (2018) 13
- 14. Common Mistakes Developers Make In Their API Blueprint Files (2018) 14
- 15. Common Mistakes Developers Make In Their RAML Files (2018) 15
- 16. 16
- 17. The Real Problem A Valid Definition Producing Bad Code 17
- 19. 19
- 21. 21 3 Errors 6 Warnings 22 Linting Issues
- 22. 22 Spectral Found It Ok
- 23. Say No to Inline Schemas OpenAPI Secret # 1 23
- 24. 24
- 25. 25
- 26. 26
- 27. 27
- 28. Don’t Miss Operation IDs OpenAPI Secret # 2 28
- 29. 29
- 30. 30
- 31. 31
- 32. Mind The Characters in Operation IDs OpenAPI Secret # 3 32
- 33. 33
- 34. 34
- 35. 35
- 36. 36
- 37. Avoid Schema Key Confusions OpenAPI Secret # 4 37
- 38. 38
- 39. 39
- 40. 40
- 41. Some Minor, yet Important Considerations 41
- 42. Keep the Parameters in Order 42 OpenAPI Secret # 5
- 43. 43
- 44. 44
- 45. 45
- 46. Very Long Names Hurt User Friendliness OpenAPI Secret # 6 46
- 47. 47
- 48. 48
- 49. Operation Tags Are Helpful OpenAPI Secret # 7 49
- 50. 50
- 51. 51
- 52. SDKs beyond API Wrappers? 52
- 53. How to Validate Specs for Generating Code? 53
- 55. 55
- 56. 56 Thanks! Any questions? You can find me: adeel@apimatic.io Resources: Validator: apimatic.io/solution/fix-my-spec API Trends: apimatic.io/blog NASA API: apimatic.io/blog/2021/12/million-mile-views-via-a-nasa-api SDK Advantage Book: apimatic.io/resource/modern-guide-to-building-sdks
- 57. Credits Special thanks to all the people who made and released these awesome resources for free: Presentation template by SlidesCarnival Photographs by Unsplash 57