Generating docs from APIs
-
Upload
jamiehannaford -
Category
Technology
-
view
713 -
download
0
Transcript of Generating docs from APIs
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
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.
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.
3 popular solutions
Swagger RAML API blueprint
apiblueprint.orgraml.orgswagger.io
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?