Download as PDF, PPTX
Generating docs from APIs
- 1. Generating docs from APIs Prague,2015 @jamiehannaford
- 2. What are wegoing to talk about today? • What are some of the problems surrounding developing and documenting APIs? • How can we centralise the information we produce? Is DRY docs feasible? • How can we improve communication and team dynamics? • How can we streamline production and save time?
- 3. Some assumptions • Verybasic knowledge of HTTP/REST • Familiarity with JSON • A love of cats (all will be explained...)
- 4. What is aweb API? • An interface that allows users to perform tasks. • A contract between server and client. Specifies exactly how something can be executed. • "Defines functionalities that are independent of their respective implementations." • Documentation is tasked with communicating this API contract in a simple, effective way.
- 5. Adopt-a-cat API • Cathas an ID, name, colour, adoption status, and a selection of favourite toys. • List all cats • Retrieve details about a specific cat • Create a new cat
- 6. Implementing APIs inFlask
- 7.
- 8. How do westructure resource data?
- 10. What is JSONSchema? • A way of modelling an API resource, like a cat, in JSON. What properties does it have? What are their types? How would you describe them? • Keywords allow us to add meaning and contextualise arbitrary blobs of JSON. • Allows us to translate our assumptions into a consistent format for users to consume.
- 11. Making sense ofour JSON blob
- 12.
- 13.
- 14.
- 15.
- 17. What does itoffer us? • Centralise representation data of our models. • Free from implementation details. • Standardised, consistent validation. • A human- and machine-readable document to share with users.
- 18. But it's notenough...
- 19. 3 popular solutions SwaggerRAML API blueprint apiblueprint.orgraml.orgswagger.io
- 20.
- 21.
- 22.
- 23.
- 24.
- 25.
- 26. Wrap-up • What aresome of the problems we experience? • Projects that can help us: Swagger, RAML, Apiary. • Define once, re-use everywhere. Forgo the normal problems of duplication and knowledge gaps. • Why be excited about them?
- 27. Thank you! (Děkuji!) Slides availablelater @jamiehannaford