SlideShare a Scribd company logo

Generating docs from APIs

•
•
J
jamiehannaford

APIs define contracts between a service and a client, and with the rise of representation languages like Swagger, Apiary, and RAML, these contracts can be consumed programmatically and adapted easily into our codebases. Other tools like JSON Schema also contribute to this idea of integration between service and client. But what about our documentation? If API contracts can be assimilated into software, surely it can drive our documentation too? In this talk, I want to introduce some of the techniques I've used on past projects that allow exactly that. By using remote schemas to generate software, it also allows us to generate working documentation that is always relevant and never out of date. Apart from accuracy, we also get the added benefits of reduced development time, reduced effort, and reduced duplication. We can all of this by documenting once, and re-using across multiple projects!

1 of 27
Download to read offline
Generating docs from APIs Prague, 2015 @jamiehannaford
What are we going 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?
Some assumptions • Very basic knowledge of HTTP/REST • Familiarity with JSON • A love of cats (all will be explained...)
What is a web 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.
Adopt-a-cat API • Cat has 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
Implementing APIs in Flask
Does it work?!
How do we structure resource data?
Generating docs from APIs
What is JSON Schema? • 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.
Making sense of our JSON blob
"colour" property
"name" property
"status" property
"toys" property
Generating docs from APIs
What does it offer us? • Centralise representation data of our models. • Free from implementation details. • Standardised, consistent validation. • A human- and machine-readable document to share with users.
But it's not enough...
3 popular solutions Swagger RAML API blueprint apiblueprint.orgraml.orgswagger.io
Hierarchical paths
Operation parameters
Generate docs
Documenting parameters
Sandbox
Generating clients
Wrap-up • What are some 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?
Thank you! (Děkuji!) Slides available later @jamiehannaford

More Related Content

Generating docs from APIs

  • 1. Generating docs from APIs Prague, 2015 @jamiehannaford
  • 2. What are we going 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 • Very basic knowledge of HTTP/REST • Familiarity with JSON • A love of cats (all will be explained...)
  • 4. What is a web 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 • Cat has 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
  • 8. How do we structure resource data?
  • 10. What is JSON Schema? • 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 of our JSON blob
  • 17. What does it offer 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 not enough...
  • 19. 3 popular solutions Swagger RAML API blueprint apiblueprint.orgraml.orgswagger.io
  • 26. Wrap-up • What are some 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 available later @jamiehannaford