Description
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!